Storefront API Getting Started
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.
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 Admin API.
- From your Shopify admin, select Apps.
- Click Manage private apps.
- Click Create new private app.
- Fill out the details of your private app.
- In the Storefront API section, be sure to select Allow this app to access your storefront data using the Storefront API.
- 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'll 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.
To create the storefront access token:
- Ensure 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 get your storefront access token, you're ready to access the Storefront API GraphQL endpoint.
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.
To configure GraphiQL
- Launch GraphiQL.
- In the upper-right portion 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 dropdown menu.
- For GraphQL endpoint specify
<shop>is the domain of your shop.
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:
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.
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'll 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.