Storefront API Learning Kit

Storefront API learning kit

TheStorefront APIis 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 commerceweb 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

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 israte limitedper 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 arebase64encoded. This means instead of the ID looking likegid://shopify/Collection/1it will look likeZ2lkOi8vc2hvcGlmeS9Db2xsZWN0aW9uLzE=.

Setup

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

If you’re not already familiar with GraphQL, please consult theShopify GraphQL Learning Kitbefore proceeding.

Step 1: Create an app

To get started, you will need to create aprivate 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 theImport/Exportwindow in Insomnia:

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

From theDatatab, selectImportand 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
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_urlwill be the Shopify store being connected to. If your store ismydevstore.myshopify.com, entermydevstore.myshopify.comhere.

2.api_versionis 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_tokenis used to populate theX-Shopify-Storefront-Access-Tokenrequest 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.

让你的第一个请求

In the image below, you should see at the top of the frame that we're using thebase_urlandapi_versionto build out the address for the endpoint. You can also clickHeaderat the top to see the use of thestorefront_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 weannounced cart capabilitiesin 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, thecheckoutUrlcan 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 thecheckoutUrl.

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.

Grow your business with the Shopify Partner Program

Learn more