Getting started with Shopify Storefront API

The Storefront API provides unauthenticated access to customers, checkouts, product collections, and other store resources that you can use to build purchasing experiences on merchant storefronts. For more information, see Sample integration.

Storefront API authentication

To authenticate with the Storefront API as either a private or public app, you need to obtain a storefront access token with the unauthenticated access scopes. As a private app, you can obtain the token when creating a private app in the Shopify admin. As a public app, you need to obtain the token by using OAuth. You need to include the token in a request header to access the Storefront API:

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

Private app

When building a private app, you can obtain a storefront access token by creating a private app.

Steps:

  1. From your Shopify admin, select Apps.
  2. Click Manage private apps.
  3. Click Create a new private app.
  4. Fill out the details of your private app.

  5. In the Storefront API section, select Allow this app to access your storefront data using the Storefront API.

  6. In the Storefront API permissions section, select which types of data you want to expose to the app.

    Four permissions are selected by default:

    • Read products, variants, and collections
    • Read and modify customer data
    • Read and modify checkouts
    • Read content like articles, blogs, and comments

  7. Click Save.

  8. After you save the app, you can find the generated storefront access token in the Storefront API section.

Public app

To authenticate to the Storefront API as a public app you need to turn your app into a sales channel. When your app is a sales channel, you can request merchant permission for the unauthenticated Storefront API scopes by using OAuth. If your app is granted access, then you can use the app's access token to request the storefront access token.

Making your app a sales channel

After you've created an app from your Partner Dashboard, you can go to App setup and turn the app into a sales channel.

When you make an app a sales channel, you can request payment processing, which you can use to complete payments with the Storefront API. You can use the unauthenticated_write_checkouts scope and payment processing permissions to create and complete checkouts. To learn about the payment completion options, see Creating a checkout.

Requesting unauthenticated scopes

You request unauthenticated scopes as part of OAuth. After a merchant makes an install request, your app redirects to Shopify to load the the OAuth grant screen that displays the unauthenticated Storefront API scopes. The following example URL shows the requested scopes:

View example 

https://{store_domain}.myshopify.com/admin/oauth/authorize?client_id={client_id}&scope=unauthenticated_read_product_listings,unauthenticated_write_checkouts,unauthenticated_write_customers,unauthenticated_read_customer_tags,unauthenticated_read_content,unauthenticated_read_product_tags&redirect_uri=https://www.google.com/&state=nonce1

For more information about OAuth see OAuth.

Requesting the storefront access token

After completing OAuth by exchanging the access code for a permanent access token, you can request a storefront access token. To get the token, send a POST request to the StorefrontAccessToken resource with your app's access token as a request header. The API returns the storefront access token with a list of unauthenticated scopes requested by your app.

View response 

{
  "storefront_access_token": {
    "access_token": "{token}",
    "access_scope": "unauthenticated_read_content,unauthenticated_read_customer_tags,unauthenticated_read_product_tags,unauthenticated_read_product_listings,unauthenticated_write_checkouts,unauthenticated_read_checkouts,unauthenticated_write_customers,unauthenticated_read_customers",
    "created_at": "2019-05-09T17:05:22-04:00",
    "id": 22143565880,
    "admin_graphql_api_id": "gid://shopify/StorefrontAccessToken/22143565880",
    "title": "Test"
  }
}

You can then use the storefront access token as a request header in your calls to the Storefront API:

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

Accessing the Storefront API GraphQL endpoint

You can access the Storefront API 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.

Steps:

  1. Launch GraphiQL.
  2. Click Edit HTTP Headers.
  3. Add a header and set its name to X-Shopify-Storefront-Access-Token. For the value, use your generated storefront access token.
  4. Add a header named Accept and set its value to application/json.
  5. To return to the editor, click anywhere outside of the Edit HTTP Headers modal.
  6. Make sure that POST is selected from the drop-down menu.
  7. For the GraphQL endpoint, enter https://<my_domain.com>/api/2019-07/graphql, where <my_domain.com> is the domain of your shop. The domain must be either a connected domain or your shop's <shop>.myshopify.com domain.
  8. Run a query to access the Storefront API.

The following example returns the shop information:

Post /api/2019-07/graphql.json

{
  shop {
    name
    primaryDomain {
      url
      host
    }
  }
}

JSON response:

{
  "data": {
    "productByHandle": {
      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg="
    }
  }
}

You can also use curl to to retrieve the product ID:

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

Collection ID

The following example returns the collection ID that corresponds to the handle:

Post /api/2019-07/graphql.json

{
  collectionByHandle(handle: "bicycles") {
    id
  }
}

JSON response:

{
  "data": {
    "node": {
      "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg=",
      "title": "red bicycle"
    }
  }
}

Fetch a customer

To retrieve a customer, you need to use the customer query root, and specify the customer by providing their customerAccessToken for identification. To learn how to create a customerAcessToken see Updating customers.

The following example returns the customer information associated to the access token:

Post /api/2019-07/graphql.json

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

JSON response:

{
  "data": {
    "customer": {
      "orders": {
        "edges": [
          {
            "node": {
              "lineItems": {
                "edges": [
                  {
                    "node": {
                      "quantity": 1,
                      "title": "red bicycle"
                    }
                  },
                  {
                    "node": {
                      "quantity": 1,
                      "title": "blue bicycle"
                    }
                  },
                  {
                    "node": {
                      "quantity": 1,
                      "title": "green bicycle"
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Sample integration

This sample integration demonstrates how to build a mobile app builder. The integration embeds in the Shopify admin and makes a mobile app storefront by using the Storefront API and the Mobile Buy SDK:

Embedded App

Shopify provides the Embed in Shopify admin app extension to integrate your app seamlessly with the Shopify admin. Shopify also supports the Shopify App Bridge which is a a JavaScript library that works with the app extension. You can use Shopify Polaris to build rich and responsive experiences. Polaris is also designed to work directly with Shopify App Bridge.

By using these tools, you can embed the app's configuration pages inside of Shopify admin. Merchants use these pages to to configure the look and features of their mobile storefront apps.

Storefront

Using the Mobile Buy SDK for iOS and Android, you can access storefront data such as customers, store resources, and checkouts. When building checkout experiences, you can choose from a variety of ways to complete payments for maximum flexibility and limited PCI liability.

Shopify

On the backend, Shopify handles all calls to the GraphQL Admin API. On the storefront, Shopify enables you to use checkouts, payment processing, customer management, and product data retrieval on the storefront.

Example API workflows

After you've created a public and, turned it into a sales channel, and obtained a storefront access token, you can use the following steps and APIs to build the sample integration:

  1. Use the following tools to build the Shopify admin integration

  2. Use the Storefront API and Mobile Buy SDK to access the public storefront data. Using the Mobile Buy SDK

    Create checkouts and complete payments

    Manage customers

    Query shop resources

  3. Implement mobile app features to increase customer engagement

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.

Storefront API Rate Limits

The Storefront API rate limits use a leaky bucket algorithm. The algorithm lets your app make an unlimited amount of requests in infrequent bursts over time.

After the limit is exceeded, all requests are throttled and return an {errors: [{ message: "Throttled" }]} error. Requests succeed again after enough points have accumulated in the bucket. Responses don't currently include information about the cost of the query or the state of the throttle.

Rate limits

The bucket's unit of measurement is the elapsed time in seconds that it takes to complete a request. The bucket size is 60 seconds, and this can't be exceeded at any given time or a throttling error is returned. The bucket empties at a leak rate of one per second.

The 60-second limit applies to the IP address of the buyer interacting with the app, rather than the ID of the shop where the app is installed. This means your app won't be throttled due to an increase in buyer traffic on a merchant's shop.

Every request to the Storefront API costs at least 0.5 seconds to run. After a request completes, the total elapsed time is calculated and subtracted from the bucket.

Bucket limit example

Suppose that client requests to an app only take 0.5 seconds or less. Each request would cost the minimum 0.5 seconds. In this scenario, it's possible for a client to make a maximum of 120 parallel requests while remaining within the 60 second bucket limit (120=60/0.5).

Recommendations to avoid throttling errors

Designing your app with best practices in mind is the best way to avoid throttling errors. For example, you can stagger API requests in a queue and do other processing tasks while waiting for the next queued job to run. Consider the following best practices when designing your app:

  • Include code that catches the errors object. If you ignore these errors and keep trying to make requests, then your app won't be able to gracefully recover.
  • Your code should stop making additional API requests until enough time has passed to retry. The recommended backoff time is 1000 ms.
  • Optimize your code to only get the data that your app requires.
  • Use caching for data that your app uses often.
  • Regulate the rate of your requests for smoother distribution.