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:

  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.

    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

  7. Click Save.

  8. 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:

  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://{shop}.myshopify.com/api/2021-01/graphql.json.
  8. 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
    }
  }
}

View response

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
    }
  }
}
'

View response

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
  }
}

View response

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
  }
}

View response

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
    }
  }
}

View response

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
              }
            }
          }
        }
      }
    }
  }
}

View response

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:

  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:

    Create checkouts and complete payments

    Manage customers

    Query shop resources

  3. Implement mobile app features to increase customer engagement:

Next steps