Storefront API Learning Kit

The Storefront API is a GraphQL API that powers customer facing experiences. It is device-agnostic and enables developers to build custom storefronts. You use the Storefront API to build API-powered commerce such as mobile apps, headless commerce web experiences, Internet of Things (IoT), voice commerce, and more. Shopify is one of the largest API-first commerce (also known as headless) providers in the world, and these unique experiences are built with this feature-rich API.

This learning kit will help familiarize you with the Storefront API and serve as a developer tool to increase your velocity when building. It will walk you through making your first request, as well as give advice and best practices on the commerce capabilities required to build a custom storefront.

Admin API vs. Storefront API
Setup
Making your first request
Retrieving products
Managing a cart

Admin API vs. Storefront API

It is important to differentiate between the GraphQL Admin API and the GraphQL Storefront API. Given that the Storefront API is intended for customer-facing experiences, it is a public API which is designed to be used client-side. This means the access token used for authentication is not secret and can be used in places where it will be exposed.

The Admin API key and password, however, should never be used client side. The Admin API is for admin-related actions and provides extensive access to data. It gives you read and write access to store information, including about products, inventory, orders, shipping, and more. In comparison, the Storefront API is primarily read access only, with the exception of authentication and managing a cart.

Other important characteristics of the Storefront API include:

Rate limits: The Storefront API is rate limited per buyer IP, which scales and handles large amounts of customer requests with ease.
IDs: Unlike the Admin API, all resource IDs in the Storefront API are base64 encoded. This means instead of the ID looking like gid://shopify/Collection/1 it will look like Z2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzE=.

Setup

In order to follow along with this walkthrough, you’ll need a few things:

Your own private app that you’ve created on your store
The Insomnia API client
The Storefront API Learning Kit Collection. To download this collection, find the latest build here, click “raw” and save the file.

If you’re not already familiar with GraphQL, please consult the Shopify GraphQL Learning Kit before proceeding.

Step 1: Create an app

To get started, you will need to create a private app. Once you have created the private app, there is a Storefront API section found at the bottom of the app overview page. This is where you can set your permissions and copy the access token.

Storefront API learning kit: screenshot of the Storefront API Permissions page with green box surrounding the access token sequence — Retrieving the Storefront access token from the private app page.

Step 2: Download the collection

You will need to download the walkthrough as a collection, and import it into Insomnia.

To do this, open the Import/Export window in Insomnia:

Storefront API learning kit: screenshot of Insomnia displaying a dropdown menu with import/export options — The Import/Export window in Insomnia.

From the Data tab, select Import and choose the file you have downloaded.

Storefront API learning kit: screenshot of Insomnia displaying options to export data, import data, or create a run button. Under the import data option there's a drop-down menu with the options "from file," "from URL," or "from Clipboard." A green box surrounding "from File" — Importing the file.

Step 3: Configure your environment variables

Environment variables are JSON key-value pairs that allow you to refer to values without having to write them out every time. For this tutorial, we’ll use three environment variables:

1. base_url will be the Shopify store being connected to. If your store is mydevstore.myshopify.com, enter mydevstore.myshopify.com here.

2. api_version is the Storefront API version used for the API requests. This can be changed to an earlier or unstable version depending on your use case.

3. storefront_access_token is used to populate the X-Shopify-Storefront-Access-Token request header. The storefront access token is generated when creating a private app.

Storefront API learning kit: screenshot of Insomnia displaying an option to manage the environment variables on the left hand site, that is indicated by a green box — Where to manage environment variables in Insomnia.

Storefront API learning kit: screenshot of Insomnia displaying an example base environment with 3 variables — An example environment setup with variables.

Making your first request

In the image below, you should see at the top of the frame that we're using the base_url and api_version to build out the address for the endpoint. You can also click Header at the top to see the use of the storefront_access_token.

Once you've confirmed these three fields are set in your environment, try running the first query in the kit. If the Storefront API access token has been configured correctly, you should get your shop’s info back.

Storefront API learning kit: screenshot of Insomnia displaying the initial request for querying shop data with lines of code on both the left and right hand side of the screen. — Initial request querying shop data.

If you are not receiving any information back, please check the previous steps again to ensure your environment is set up correctly.

Retrieving products

Now that you’ve confirmed that the correct shop data is returned, you can start to explore more of what the Storefront API has to offer.

Let’s begin by retrieving three products along with the first three variants. You can update these numbers to return different amounts of data depending on your unique use case. Below is an example of the response you will get returned.

Storefront API learning kit: screenshot of Insomnia displaying the outcome of retrieving 3 products and variables in lines of code. The left hand side is the request, the right hand side the outcome — The response when retrieving three products and three variants.

As you can see in the response, everything that we requested in GraphQL is returned and nothing more. This is one of the major benefits of a GraphQL API. Once you have the product and variant IDs, you can query them directly and use them to populate other requests in the collection.

Managing a cart

At Unite 2021 we announced cart capabilities in the Storefront API. The cart is powered by the same primitives as our checkout, but designed to provide predictable low latency responses without hitting checkout rate limits. Once you have the ID of at least one variant, you can create a cart.

Storefront API learning kit: screenshot from insomnia displaying the request to create the initial cart on the left hand side, and the response on the right hand side. — The request and response creating the initial cart.

The returned cart id can be used to query the cart object, if you need to reference it during the customer experience later. This will be used to add subsequent items to the cart or more customer details.

Storefront API learning kit: screenshot from insomnia of the coded response when querying an already created cart — The response when querying a created cart.

If you want to associate your customer to the cart you can do so by attaching a buyer identity to the cart. This associates the customer which can be useful for applicable discounts or prefilling the checkout.

Storefront API learning kit: screenshot from Insomnia displaying the response from associating a customer to their cart with their buyer identity — Associating a customer to the cart with their buyer identity.

Lastly, the checkoutUrl can be retrieved from the cart which will be used to redirect the customer to Shopifys checkout.

Storefront API learning kit: screenshot from Insomnia displaying a query for the cart to display the Checkout URL — Querying the cart to return the `checkoutUrl`.

Building unique commerce experiences

Now that you’re getting the hang of the Storefront API, you can increase the complexity of the queries you make. The collection will walk you through setting up metafields, products, customers, collections, creating a cart, and more advanced topics like Buy Online Pick Up In Store (BOPIS), subscriptions, and international pricing.

Use the Storefront API learning kit to start brainstorming and troubleshooting your next innovative commerce build.

Table of contents