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.

Choose a version:

Anchor to Development frameworks and SDKsDevelopment frameworks and SDKs

Use Shopify’s officially supported libraries to build fast, reliable apps with the programming languages and frameworks you already know.

cURL

Use the curl utility to make API queries directly from the command line.

Hydrogen

A React-based framework for building custom storefronts on Shopify, Hydrogen has everything you need to build fast, and deliver personalized shopping experiences.

Storefront API Client

The official lightweight client for any Javascript project interfacing with Storefront API and our recommended client for building custom storefronts without Hydrogen.

Remix (Apps)

The official package for Remix applications, with full TypeScript support.

Node.js

The official client library for Node.js applications, with full TypeScript support. It has no framework dependencies, so it can be used by any Node.js app.

Shopify API (Apps)

The full suite library for TypeScript/JavaScript Shopify apps to access the GraphQL and REST Admin APIs and the Storefront API.

Ruby

The official client library for Ruby applications. It has no framework dependencies, so it can be used by any Ruby app. This API applies a rate limit based on the IP address making the request, which will be your server’s address for all requests made by the library. Learn more about rate limits.

Android

The official client library for Android apps.

iOS

The official client library for iOS applications.

Other

Other libraries are available in addition to the ones listed here. Check the list of developer tools for custom storefronts.

npm init @shopify/hydrogen

// or

npx @shopify/create-hydrogen

// or

pnpm create @shopify/create-hydrogen

// or

yarn create @shopify/hydrogen

npm install --save @shopify/storefront-api-client

// or

yarn add @shopify/storefront-api-client

npm install --save @shopify/shopify-app-remix

// or

yarn add @shopify/shopify-app-remix

npm install --save @shopify/shopify-api

// or

yarn add @shopify/shopify-api

bundle add shopify_api

npm init @shopify/hydrogen
// or
npx @shopify/create-hydrogen
// or
pnpm create @shopify/create-hydrogen
// or
yarn create @shopify/hydrogen

npm install --save @shopify/storefront-api-client
// or
yarn add @shopify/storefront-api-client

npm install --save @shopify/shopify-app-remix
// or
yarn add @shopify/shopify-app-remix

npm install --save @shopify/shopify-api
// or
yarn add @shopify/shopify-api

bundle add shopify_api

Anchor to AuthenticationAuthentication

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.

curl -X POST \

https://{shop}.myshopify.com/api/2025-04/graphql.json \

-H 'Content-Type: application/json' \

-H 'X-Shopify-Storefront-Access-Token: {storefront-access-token}' \

-d '{

"query": "{your_query}"

const storefront = createStorefrontClient({

publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,

storeDomain: `https://\${env.PUBLIC_STORE_DOMAIN}\`,

storefrontApiVersion: env.PUBLIC_STOREFRONT_API_VERSION || '2023-01',

});

import {createStorefrontApiClient} from '@shopify/storefront-api-client';

const client = createStorefrontApiClient({

storeDomain: 'http://your-shop-name.myshopify.com',

apiVersion: '2025-04',

publicAccessToken: <your-storefront-public-access-token>,

});

import { authenticate, unauthenticated } from "../shopify.server";

// Use private access token on requests that don't come from Shopify

const { storefront } = await unauthenticated.storefront(shop);

// OR

// Use private access token for app proxy requests

const { storefront } = await authenticate.public.appProxy(request);

const adminApiClient = new shopify.clients.Rest({session});

const storefrontTokenResponse = await adminApiClient.post({

path: 'storefront_access_tokens',

type: DataType.JSON,

data: {

storefront_access_token: {

title: 'This is my test access token',

});

const storefrontAccessToken =

storefrontTokenResponse.body['storefront_access_token']['access_token'];

# Create a REST client from your offline session

client = ShopifyAPI::Clients::Rest::Admin.new(

session: session

)

# Create a new access token

storefront_token_response = client.post(

path: 'storefront_access_tokens',

body: {

storefront_access_token: {

title: "This is my test access token",

}

)

storefront_access_token = storefront_token_response.body['storefront_access_token']['access_token']

curl -X POST \
  https://{shop}.myshopify.com/api/2025-04/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Storefront-Access-Token: {storefront-access-token}' \
  -d '{
    "query": "{your_query}"
  }'

const storefront = createStorefrontClient({
publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
storeDomain: `https://\${env.PUBLIC_STORE_DOMAIN}\`,
storefrontApiVersion: env.PUBLIC_STOREFRONT_API_VERSION || '2023-01',
});

import {createStorefrontApiClient} from '@shopify/storefront-api-client';

const client = createStorefrontApiClient({
  storeDomain: 'http://your-shop-name.myshopify.com',
  apiVersion: '2025-04',
  publicAccessToken: <your-storefront-public-access-token>,
});

import { authenticate, unauthenticated } from "../shopify.server";

// Use private access token on requests that don't come from Shopify
const { storefront } = await unauthenticated.storefront(shop);
// OR
// Use private access token for app proxy requests
const { storefront } = await authenticate.public.appProxy(request);

const adminApiClient = new shopify.clients.Rest({session});
const storefrontTokenResponse = await adminApiClient.post({
  path: 'storefront_access_tokens',
  type: DataType.JSON,
  data: {
    storefront_access_token: {
      title: 'This is my test access token',
    },
  },
});

const storefrontAccessToken =
  storefrontTokenResponse.body['storefront_access_token']['access_token'];

# Create a REST client from your offline session
client = ShopifyAPI::Clients::Rest::Admin.new(
  session: session
)

# Create a new access token
storefront_token_response = client.post(
  path: 'storefront_access_tokens',
  body: {
    storefront_access_token: {
      title: "This is my test access token",
    }
  }
)

storefront_access_token = storefront_token_response.body['storefront_access_token']['access_token']

Anchor to Endpoints and queriesEndpoints 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:

https://{store_name}.myshopify.com/api/2025-04/graphql.json

Anchor to VersioningVersioning

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.

Anchor to GraphiQL explorerGraphiQL 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.

Anchor to Usage limitationsUsage 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.

POST

https://{store_name}.myshopify.com/api/2025-04/graphql.json

# Get the ID and title of the three most recently added products

curl -X POST \

https://{store_name}.myshopify.com/api/2025-04/graphql.json \

-H 'Content-Type: application/json' \

-H 'X-Shopify-Storefront-Access-Token: {storefront_access_token}' \

-d '{

"query": "{

products(first: 3) {

edges {

node {

title

}

import {json} from '@shopify/remix-oxygen';

export async function loader({context}) {

const PRODUCTS_QUERY = `#graphql

query products {

products(first: 3) {

edges {

node {

title

}

const {products} = await context.storefront.query(PRODUCTS_QUERY);

return json({products});

}

const productQuery = `

query ProductQuery($handle: String) {

product(handle: $handle) {

title

handle

}

const {data, errors, extensions} = await client.request(productQuery, {

variables: {

handle: 'sample-product',

});

const { storefront } = await unauthenticated.storefront(

'your-development-store.myshopify.com'

);

const response = await storefront.graphql(

`#graphql

query products {

products(first: 3) {

edges {

node {

title

}

}`,

);

const data = await response.json();

// Load the access token as per instructions above

const storefrontAccessToken = '<my token>';

// Shop from which we're fetching data

const shop = 'my-shop.myshopify.com';

// StorefrontClient takes in the shop url and the Storefront Access Token for that shop.

const storefrontClient = new shopify.clients.Storefront({

domain: shop,

storefrontAccessToken,

});

// Use client.query and pass your query as \`data\`

const products = await storefrontClient.query({

data: `{

products (first: 3) {

edges {

node {

title

}

}`,

});

# Load the access token as per instructions above

store_front_access_token = '<my token>'

# Shop from which we're fetching data

shop = 'my-shop.myshopify.com'

# The Storefront client takes in the shop url and the Storefront Access Token for that shop.

storefront_client = ShopifyAPI::Clients::Graphql::Storefront.new(

shop,

storefront_access_token

)

# Call query and pass your query as `data`

my_query = <<~QUERY

{

products (first: 3) {

edges {

node {

title

}

QUERY

products = storefront_client.query(query: my_query)

# Get the ID and title of the three most recently added products
curl -X POST \
  https://{store_name}.myshopify.com/api/2025-04/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Storefront-Access-Token: {storefront_access_token}' \
  -d '{
    "query": "{
      products(first: 3) {
        edges {
          node {
            id
            title
          }
        }
      }
    }"
  }'

import {json} from '@shopify/remix-oxygen';

export async function loader({context}) {
  const PRODUCTS_QUERY = `#graphql
    query products {
      products(first: 3) {
        edges {
          node {
            id
            title
          }
        }
      }
    }
  `;
  const {products} = await context.storefront.query(PRODUCTS_QUERY);
  return json({products});
}

const productQuery = `
  query ProductQuery($handle: String) {
    product(handle: $handle) {
      id
      title
      handle
    }
  }
`;

const {data, errors, extensions} = await client.request(productQuery, {
  variables: {
    handle: 'sample-product',
  },
});

const { storefront } = await unauthenticated.storefront(
  'your-development-store.myshopify.com'
);

const response = await storefront.graphql(
  `#graphql
  query products {
    products(first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }`,
);

const data = await response.json();

// Load the access token as per instructions above
const storefrontAccessToken = '<my token>';
// Shop from which we're fetching data
const shop = 'my-shop.myshopify.com';

// StorefrontClient takes in the shop url and the Storefront Access Token for that shop.
const storefrontClient = new shopify.clients.Storefront({
  domain: shop,
  storefrontAccessToken,
});

// Use client.query and pass your query as \`data\`
const products = await storefrontClient.query({
  data: `{
    products (first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }`,
});

# Load the access token as per instructions above
store_front_access_token = '<my token>'
# Shop from which we're fetching data
shop = 'my-shop.myshopify.com'

# The Storefront client takes in the shop url and the Storefront Access Token for that shop.
storefront_client = ShopifyAPI::Clients::Graphql::Storefront.new(
  shop,
  storefront_access_token
)

# Call query and pass your query as `data`
my_query = <<~QUERY
  {
    products (first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
QUERY
products = storefront_client.query(query: my_query)

Anchor to DirectivesDirectives

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.

Anchor to Storefront DirectivesStorefront Directives

@inContext (Country Code)

In the Storefront API, the @inContext 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 @inContext(country: FR).

@inContext (Language)

In the Storefront API, beyond version 2022-04, the @inContext directive can contextualize any query to one of a shop's available languages with an optional language code argument.

This example shows how to return a product's title, description, and options translated into Spanish @inContext(language: ES).

@inContext (Buyer Identity)

In the Storefront API, beyond version 2024-04, the @inContext directive can contextualize any query to a logged in buyer of a shop with an optional buyer argument.

This example shows how to return a product's price amount contextualized for a business customer buyer @inContext(buyer: {customerAccessToken: 'token', companyLocationId: 'gid://shopify/CompanyLocation/1'}).

@defer

The @defer directive allows clients to prioritize part of a GraphQL query without having to make more requests to fetch the remaining information. It does this through streaming, where the first response contains the data that isn't deferred.

The directive accepts two optional arguments: label and if. The label is included in the fragment response if it's provided in the directive. When the if argument is false, the fragment isn't deferred.

This example shows how to return a product's title and description immediately, and then return the descriptionHtml and options after a short delay.

The @defer directive is available as a developer preview in unstable.

Examples for how to use @defer

Operation

query productDetails {

productByHandle(handle: "baseball-t-shirt") {

title

description

... @defer(label: "Extra info") {

descriptionHtml

options {

name

values

}

Response

JSON

--graphql

Content-Type: application/json

Content-Length: 158

{

"data": {

"productByHandle": {

"title": "Baseball t-shirt",

"description": "description":"3 strikes, you're... never out of style in this vintage-inspired tee."

}

"hasNext": true

}

--graphql

Content-Type: application/json

Content-Length: 295

{

"incremental": [{

"path": ["productByHandle"],

"label": "Extra info",

"data": {

"descriptionHtml": "<p>3 strikes, you're... never out of style in this vintage-inspired tee. </p>",

"options": [

{

"name": "Size",

"values": ["Small", "Medium", "Large"]

{

"name": "Color",

"values": ["White", "Red"]

}

]

}

}],

"hasNext": false

}

--graphql--

Anchor to Rate limitsRate 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.

Anchor to Status and error codesStatus and error codes

All API queries return HTTP status codes that contain more information about the response.

Anchor to 200 OK200 OK

The Storefront API can return a 200 OK response code in cases that would typically produce 4xx errors in REST.

Anchor to Error handlingError 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 userErrors.

Properties

errors•array

A list of all errors returned

errors[n].message•string

Contains details about the error(s).

errors[n].extensions•object

Provides more information about the error(s) including properties and metadata.

extensions.code•string

Shows error codes common to Shopify. Additional error codes may also be shown.

ACCESS_DENIED

The client doesn’t have correct authentication credentials. Similar to 401 Unauthorized.

SHOP_INACTIVE

The shop is not active. This can happen when stores repeatedly exceed API rate limits or due to fraud risk.

INTERNAL_SERVER_ERROR

Shopify experienced an internal error while processing the request. This error is returned instead of 500 Internal Server Error in most circumstances.

{}

Sample 200 error responses

{

"errors": [

{

"message": "Throttled",

"extensions": {

"code": "THROTTLED"

}

]

}

{

"errors": [

{

"message": "Internal error. Looks like something went wrong on our end.

Request ID: 1b355a21-7117-44c5-8d8b-8948082f40a8 (include this in support requests).",

"extensions": {

"code": "INTERNAL_SERVER_ERROR"

}

]

}

{
  "errors": [
    {
      "message": "Throttled",
      "extensions": {
        "code": "THROTTLED"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Internal error. Looks like something went wrong on our end.
        Request ID: 1b355a21-7117-44c5-8d8b-8948082f40a8 (include this in support requests).",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

Anchor to 4xx and 5xx status codes4xx 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.

Anchor to 400 Bad Request400 Bad Request

The server will not process the request.

Anchor to 402 Payment Required402 Payment Required

The shop is frozen. The shop owner will need to pay the outstanding balance to unfreeze the shop.

Anchor to 403 Forbidden403 Forbidden

The shop is forbidden. Returned if the store has been marked as fraudulent.

Anchor to 404 Not Found404 Not Found

The resource isn’t available. This is often caused by querying for something that’s been deleted.

Anchor to 423 Locked423 Locked

The shop isn’t available. This can happen when stores repeatedly exceed API rate limits or due to fraud risk.

Anchor to 5xx Errors5xx Errors

An internal error occurred in Shopify. Check out the Shopify status page for more information.

Info

Didn’t find the status code you’re looking for? View the complete list of API status response and error codes.

{}

Sample error codes

HTTP/1.1 400 Bad Request

{

"errors": {

"query": "Required parameter missing or invalid"

}

HTTP/1.1 402 Payment Required

{

"errors": "This shop's plan does not have access to this feature"

}

HTTP/1.1 403 Forbidden

{

"errors": "Unavailable Shop"

}

HTTP/1.1 404 Not Found

{

"errors": "Not Found"

}

HTTP/1.1 423 Locked

{

"errors": "This shop is unavailable"

}

HTTP/1.1 500 Internal Server Error

{

"errors": "An unexpected error occurred"

}

HTTP/1.1 400 Bad Request
{
  "errors": {
    "query": "Required parameter missing or invalid"
  }
}

HTTP/1.1 402 Payment Required
{
  "errors": "This shop's plan does not have access to this feature"
}

HTTP/1.1 403 Forbidden
{
  "errors": "Unavailable Shop"
}

HTTP/1.1 404 Not Found
{
  "errors": "Not Found"
}

HTTP/1.1 423 Locked
{
  "errors": "This shop is unavailable"
}

HTTP/1.1 500 Internal Server Error
{
  "errors": "An unexpected error occurred"
}

Anchor to ResourcesResources

Get started

Learn more about how the Storefront API works and how to get started with it.

Storefront Learning Kit

Explore a downloadable package of sample GraphQL queries for the Storefront API.

Developer changelog

Read about the changes currently introduced in the latest version of the Storefront API.

Was this page helpful?