Accessing the API

Overview

Merchstack is a headless API that can be accessed by your storefront to power product discovery experiences. This guide will explore how to access the Merchstack API.

At this juncture, we are assuming that you have already imported your catalog data into Merchstack. If your adoption of Merchstack started on feature sets that didn't require us to power your end-user experiences, there is a good chance this is already completed. If you are unsure, please reach out to your Merchstack account representative. You can also refer to the Catalog Integrations section of the documentation.

Base API URL

To access your data on Merchstack, you will be provided with a base API URL once you have signed up. If it has not been provided, you can contact your Merchstack account representative.

The base API URL will be unique to your Merchstack account and will look something like this:
https://test-headless.merchstack.io/
test will be replaced with your Merchstack account name.

You can also access the GraphQL Playground at this URL. The GraphQL Playground is a tool that allows you to explore the Merchstack API. You can learn more about the GraphQL Playground here: GraphQL Playground

If required, an additional or a sandbox store can be added to your Merchstack account. For doing so, please contact your Merchstack account representative.

GraphQL API

The Merchstack API is a GraphQL API. You can learn more about GraphQL here: GraphQL.org.

We recommend using Apollo Client to access the Merchstack API. Apollo Client is a GraphQL client that makes it easy to consume a GraphQL API. You can learn more about Apollo Client here: Apollo Client.

Our guide will assume that you are using Apollo Client with React to access the Merchstack API. If you are using a different view library, the concepts will still apply, but the implementation details will differ. For more information, please refer to the Apollo Client documentation for your view library here: View integrations.

Setting up the GraphQL Client

Below, we have provided a step by step guide to setting up Apollo Client with React to access the Merchstack API.

Step 1: Install Apollo Client and React Apollo Client

npm install @apollo/client react-apollo

Step 2: Create an Apollo Client instance

import { ApolloClient, InMemoryCache } from '@apollo/client'

export const client = new ApolloClient({
  uri: 'https://test-headless.merchstack.io/graphql',
  cache: new InMemoryCache(),
})

Step 3: Wrap your application in the Apollo Provider

Wrap your entire/root application component with the Apollo Provider. Add the following code:

import { ApolloProvider } from '@apollo/client'
import { client } from './apollo-client'

function App() {
  return (
    <ApolloProvider client={client}>
      {/* Your application */}
    </ApolloProvider>
  )
}

Step 4: Use the useQuery hook to access the Merchstack API

In the component where you want to access the Merchstack API, use the useQuery hook to access the Merchstack API. Add the following code:

import { gql, useQuery } from '@apollo/client'

const GET_PRODUCTS = gql`
  query GetProducts {
    products {
      items {
        id
        name
      }
    }
  }
`

function Products() {
  const { loading, error, data } = useQuery(GET_PRODUCTS)

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return data.products.items.map(({ id, name }) => (
    <div key={id}>
      <p>{name}</p>
    </div>
  ))
}