Getting started with the 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.
Authentication
To authenticate with the Storefront API as either a public app or a private app, you need to obtain a storefront access token with the unauthenticated access scopes.
- As a public app, you need to obtain the token by using OAuth.
- As a private app, you can obtain the token when creating a private app in the Shopify admin.
Include the token in your request header to access the Storefront API:
X-Shopify-Storefront-Access-Token: {storefront-access-token}
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.
Make 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, refer to Create a checkout with the Storefront API.
Request 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.
For more information about OAuth, refer to Authenticate with OAuth.
The following example URL shows the requested scopes:
https://{shop}.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
Request 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:
{
"storefront_access_token": {
"access_token": "{storefront-access-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 queries to 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:
- 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.
The following 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
Click Save.
Use the generated storefront access token in your request header.
Access the Storefront API endpoint
The Storefront API makes store resources available at a single GraphQL endpoint:
POST https://{shop}.myshopify.com/api/2021-01/graphql.json
You can access the Storefront API using the GraphiQL app, curl, or any HTTP client.
Use the GraphiQL app
We recommend downloading and installing the GraphiQL app to access your shop’s data.
Steps:
- Launch GraphiQL.
- Click Edit HTTP Headers.
- Add a header and set its name to
X-Shopify-Storefront-Access-Token
. For the value, use your generated storefront access token. - Add a header named
Accept
and set its value toapplication/json
. - 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
https://{shop}.myshopify.com/api/2021-01/graphql.json
. - Run a query to access the Storefront API.
Example request:
POST https://{shop}.myshopify.com/api/2021-01/graphql.json
The following example returns the shop information:
{
shop {
name
primaryDomain {
url
host
}
}
}
JSON response:
{
"data": {
"shop": {
"name": "graphql",
"primaryDomain": {
"url": "https://graphql.myshopify.com",
"host": "graphql.myshopify.com"
}
}
}
}
Use curl
The following example returns the shop information using curl. Replace {shop}
with your store's domain and {storefront-access-token}
with the access token you generated in the Authentication section.
POST https://{shop}.myshopify.com/api/2021-01/graphql.json
curl -X POST \
"https://{shop}.myshopify.com/api/2021-01/graphql.json" \
-H "Accept: application/json" \
-H "Content-Type: application/graphql" \
-H "X-Shopify-Storefront-Access-Token: {storefront-access-token}" \
-d '
{
collections(first: 5) {
edges {
node {
id
handle
}
}
pageInfo {
hasNextPage
}
}
}
'
JSON response:
{
"data": {
"collections": {
"edges": [
{
"node": {
"id": "Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzE1NzA3NTU3MDcxMA==",
"handle": "frontpage"
}
}
],
"pageInfo": {
"hasNextPage": false
}
}
}
}
Example queries
Use the following examples to familiarize yourself with the Storefront API.
Retrieve an ID
A common use case for the Storefront API is querying information about a single product or a collection of products. Products and collections are identified by a globally unique ID, which can be used to query for information.
Product ID
The following example returns the product ID that corresponds to the handle:
POST https://{shop}.myshopify.com/api/2021-01/graphql.json
{
productByHandle(handle: "red-bicycle") {
id
}
}
JSON response:
{
"data": {
"productByHandle": {
"id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg="
}
}
}
Collection ID
The following example returns the collection ID that corresponds to the handle:
POST https://{shop}.myshopify.com/api/2021-01/graphql.json
{
collectionByHandle(handle: "bicycles") {
id
}
}
JSON response:
{
"data": {
"collectionByHandle": {
"id": "Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzQzNjMzMjEzNTA="
}
}
}
Query a single product
To retrieve a product, you can start at the node
query root and provide the product ID:
POST https://{shop}.myshopify.com/api/2021-01/graphql.json
{
node(id: "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg=") {
id
... on Product {
title
}
}
}
JSON response:
{
"data": {
"node": {
"id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgwOTI1NDg5OTg=",
"title": "red bicycle"
}
}
}
Query 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
, refer to Creating an access token.
The following example returns the customer information associated to the access token:
POST https://{shop}.myshopify.com/api/2021-01/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"
}
}
]
}
}
}
]
}
}
}
}
Example apps
To help you get started building custom storefronts with the Storefront API, we've built some example applications.
The 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.
Sample integration
The following 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 queries 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 app, 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:
- Use the following tools to build the Shopify admin integration:
Use the Storefront API and Mobile Buy SDK to access the public storefront data:
Create checkouts and complete payments
- checkoutCreate
- weburl on Checkout object
- checkoutCompleteWithCreditCardv2
- checkoutCompleteWithTokenizedPaymentV2
Manage customers
Query shop resources
Implement mobile app features to increase customer engagement:
Next steps
- GraphQL queries: Learn how to write more detailed queries and get data across multiple resources.
- Shopify Storefront API GraphiQL explorer: Use the GraphiQL explorer to build GraphQL queries.
- GraphQL learning resources: Learn more about GraphQL and how to use it in your apps.