Storefront API Getting Started

Note

The Storefront API can only be accessed using GraphQL. If you’re not familiar with GraphQL, we encourage you to visit our GraphQL guide before proceeding further.

Authentication

The Storefront API requires a Storefront Access Token for making authenticated requests. The storefront access token can be included as a request header:

X-Shopify-Storefront-Access-Token: < storefront-access-token >

Obtaining a Storefront Access Token

You can get a storefront access token by creating a private app or by using the REST API.


After you get your Storefront Access Token, you are ready to access the Storefront GraphQL endpoint.

Accessing the Storefront GraphQL endpoint

You can access the Storefront GraphQL endpoint using GraphiQL, curl, or any HTTP client.

Using GraphiQL

We recommend downloading and installing the GraphiQL app to access your shop’s data.

To configure GraphiQL

  1. Launch GraphiQL.
  2. In the upper-right portion of the IDE, click Edit HTTP Headers.
  3. Add a header with a key of X-Shopify-Storefront-Access-Token and a value of token, where token is your generated Storefront Access token.
  4. To return to the editor, click anywhere outside of the Edit HTTP Headers modal.
  5. Make sure that POST is selected from the dropdown menu.
  6. For GraphQL endpoint specify https://<shop>.myshopify.com/api/graphql, where <shop> is the domain of your shop.

To test the Storefront API GraphQL endpoint, run the following query:

{
  shop {
    name
    primaryDomain {
      url
      host
    }
  }
}

A successful query results in the following response:

{
  "data": {
    "shop": {
      "name": "graphql",
      "primaryDomain": {
        "url": "https://graphql.myshopify.com",
        "host": "graphql.myshopify.com"
      }
    }
  }
}

If everything's configured correctly, your shop settings are displayed, and you're all set to start making Storefront API GraphQL queries!

Using curl

To make a GraphQL query, send a POST request with the following JSON payload:

curl -X POST \
"https://<shop>.myshopify.com/api/graphql" \
-H "Content-Type: application/graphql" \
-H "X-Shopify-Storefront-Access-Token: <storefront-access-token>" \
-d '
{
  shop {
    collections(first: 5) {
      edges {
        node {
          id
          handle
        }
      }
      pageInfo {
        hasNextPage
      }
    }
  }
}
'

Note

To access collections or products, you'll need to explicitly publish the products on the Product or Collection page to be read by your storefront app.

Storefront publishing

Retrieving IDs

A common use case for the Storefront API is fetching information about a single product or a collection of products.

Products and collections are identified by a globally unique Storefront ID which needs to be included in the query, as seen in the example below.

To retrieve the Storefront ID of a single product using its handle, run the following query:

{
  shop {
    productByHandle(handle: "red-bicycle") {
      id
    }
  }
}

The resultant JSON includes the Storefront ID:

{
  "data": {
    "shop": {
      "productByHandle": {
        "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzczNDE0OTkzOTk="
      }
    }
  }
}

You can also use cURL directly to retrieve the Storefront ID:

curl -X POST \
"https://<shop>.myshopify.com/api/graphql" \
-H "Content-Type: application/graphql" \
-H "X-Shopify-Storefront-Access-Token: <storefront-access-token>" \
-d '
{
  shop {
    productByHandle(handle: "red-bicycle") {
      id
    }
  }
}
'

The process is the same for a collection, but uses the collectionByHandle field instead.

Example queries

You can use the following examples to familiarize yourself with making GraphQL queries to the Storefront API.

To test any of the examples listed below, copy and paste the queries into your GraphQL IDE of choice.

Fetch a single product

To retrieve a product, you'll need to start at the node query root and provide the product id formatted as follows:

{
  node(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0Lzk4OTUyODE0NzU=") {
    id
    ... on Product {
      title
    }
  }
}

Fetch a customer

A customer is one of the query roots of the Storefront API schema and requires you to pass in the customerAccessToken for identification.

{
  customer(customerAccessToken: "da3951b043bda30c6344d634b0dcd94d") {
    orders(first: 5) {
      edges {
        node {
          lineItems(first: 5) {
            edges {
              node {
                quantity
                title
              }
            }
          }
        }
      }
    }
  }
}

Example apps

To help you get started building custom storefronts with the Storefront API, we've built some example applications.

These apps are built with a variety of open-source libraries including:

  • React + JS Buy SDK
  • React + Apollo
  • Ember + JS Buy SDK
  • Ember + Apollo

Visit our storefront-api-examples project on GitHub.