Storefront API Getting Started
The Storefront API requires a Storefront Access Token for making authenticated requests. The storefront access token can be included as a request header:
Create a storefront access token
You can create a storefront access token by creating a private app or by using the Admin API.
- From your Shopify admin, select Apps.
- Click Manage private apps.
- Click Create a new private app.
- Fill out the details of your private app.
In the Storefront API section, select Allow this app to access your storefront data using the Storefront API.
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 and collections, Read and modify customers, Read and modify checkouts, and Read blogs and articles.
- Click Save.
Public sales channel apps can create storefront access tokens that delegate unauthenticated scopes. Clients with a valid storefront access token gain unauthenticated access to the public resources of a store, and can perform operations such as reading product listings, and creating checkouts. When creating a storefront access token using the Admin API, you need to create a public app with the applicable unauthenticated access scopes. This app can then delegate the access scopes to the storefront access token.
- Make sure your public app is a sales channel. This is a requirement because the Storefront API is always in the context of a single channel.
- Make sure that your public app has the applicable unauthenticated access scopes that you want to delegate.
- Create a storefront access token as described in the reference here.
After you create your storefront access token, you're ready to access the Storefront API GraphQL endpoint.
Change permissions for a storefront access token
After you've created a storefront access token, you can change its permissions to limit what areas of a store can be accessed by the app.
From your Shopify admin, go to Apps.
Click Manage private apps.
Click the name of the app whose permissions you want to change.
In the Storefront API section, under Storefront API permissions, select which areas of the store you want the app to access. Four permissions are selected by default: Read products and collections, Read and modify customers, Read and modify checkouts, and Read blogs and articles.
In the You've made changes to your app dialog, click Save.
Accessing the Storefront API GraphQL endpoint
You can access the Storefront API GraphQL endpoint using GraphiQL, curl, or any HTTP client.
We recommend downloading and installing the GraphiQL app to access your shop’s data.
- Launch GraphiQL.
- In the upper-right part of the IDE, click Edit HTTP Headers.
- Add a header with a key of
X-Shopify-Storefront-Access-Tokenand a value of
tokenis your generated Storefront Access token.
- To return to the editor, click anywhere outside of the Edit HTTP Headers modal.
- Make sure that POST is selected from the drop-down menu.
- For the GraphQL endpoint enter
<my_domain.com>is the domain of your shop. The domain must be either a connected domain or your shop's
To test the Storefront API GraphQL endpoint, run the following query:
A successful query results in the following response:
If everything's configured correctly, your shop settings are displayed, and you're all set to start making Storefront API GraphQL queries!
To make a GraphQL query, send a POST request with the following JSON payload:
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:
The resultant JSON includes the Storefront ID:
You can also use cURL directly to retrieve the Storefront ID:
The process is the same for a collection, but uses the
collectionByHandle field instead.
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 need to start at the
node query root and provide the product
id formatted as follows:
Fetch a customer
customer is one of the query roots of the Storefront API schema and requires you to pass in the
customerAccessToken for identification.
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.