GraphQL Storefront API
Create unique customer experiences with the Storefront API on any platform, including the web, apps, and games. The API offers a full range of commerce options making it possible for customers to view products and collections, add products to a cart, and check out.
Explore Hydrogen, Shopify’s official React-based framework for building headless commerce at global scale.
Development frameworks and SDKs
Use Shopify’s officially supported libraries to build fast, reliable apps with the programming languages and frameworks you already know.
Authentication
The Storefront API is unauthenticated, meaning all users have read-only access, with no username or password required.
Apps that enable the Storefront API must explicitly request relevant unauthenticated access scopes during OAuth, or during authentication in the Shopify admin.
Requests to the GraphQL Storefront API require a valid Shopify access token.
The Storefront API has the following types of access:
Public access: Used to query the API from a browser or mobile app.
Private access: Used to query the API from a server or other private context, like a Hydrogen backend.
Learn more about access tokens for the Storefront API.
Endpoints and queries
The Storefront API is available only in GraphQL. There's no REST API for storefronts.
All Storefront API queries are made on a single GraphQL endpoint, which only accepts POST requests:
Versioning
The Storefront API is versioned, with new releases four times a year. To keep your app stable, make sure that you specify a supported version in the URL.
GraphiQL explorer
Explore and learn Shopify's Storefront API using the GraphiQL explorer. To build queries and mutations with shop data, install Shopify's GraphiQL app.
Usage limitations
Shopify Plus bot protection is only available for the Cart object. It isn't available for the Checkout object.
You can’t use Storefront API to duplicate existing Shopify functionality — be sure to check the API terms of service before you start.
Directives
A directive provides a way for apps to describe additional options to the GraphQL executor. It lets GraphQL change the result of the query or mutation based on the additional information provided by the directive.
Storefront Directives
In the Storefront API, the directive takes an optional country code argument and applies this to the query or mutation.
This example shows how to retrieve a list of available countries and their corresponding currencies for a shop that's located in France .
Rate limits
The Storefront API is designed to support businesses of all sizes. The Storefront API will scale to support surges in buyer traffic or your largest flash sale. There are no rate limits applied on the number of requests that can be made to the API.
The Storefront API provides protection against malicious users, such as bots, from consuming a high level of capacity. If a request appears to be malicious, Shopify will respond with a 430 Shopify Security Rejection
error code to indicate potential security concerns. Ensure requests to the Storefront API include the correct Buyer IP header.
Status and error codes
All API queries return HTTP status codes that contain more information about the response.
200 OK
The Storefront API can return a 200 OK response code in cases that would typically produce 4xx errors in REST.
Error handling
The response for the errors object contains additional detail to help you debug your operation.
The response for mutations contains additional detail to help debug your query. To access this, you must request .
Properties
- errorsarray
A list of all errors returned
4xx and 5xx status codes
The 4xx and 5xx errors occur infrequently. They are often related to network communications, your account, or an issue with Shopify’s services.
Many errors that would typically return a 4xx or 5xx status code, return an HTTP 200 errors response instead. Refer to the 200 OK section above for details.
400 Bad Request
The server will not process the request.
402 Payment Required
The shop is frozen. The shop owner will need to pay the outstanding balance to unfreeze the shop.
403 Forbidden
The shop is forbidden. Returned if the store has been marked as fraudulent.
404 Not Found
The resource isn’t available. This is often caused by querying for something that’s been deleted.
423 Locked
The shop isn’t available. This can happen when stores repeatedly exceed API rate limits or due to fraud risk.
5xx Errors
An internal error occurred in Shopify. Check out the Shopify Shopify status page for more information.
Didn’t find the status code you’re looking for? View the complete list of API status response and error codes.