Choose a version:

Storefront API

Requires the api_access capability enabled in shopify.extension.toml.

The Storefront API provides access to Shopify's Storefront API from within a checkout extension. Use this API to fetch product details, load collection data, and query any resource available through Shopify's Storefront API.

Anchor to Use casesUse cases

Fetch product recommendations: Query the Storefront API to load related products and display cross-sell or upsell offers in checkout.
Load collection metadata: Retrieve collection details to show contextual information about items in the buyer's cart.
Access inventory or variant data: Query product variants and inventory levels to display availability or delivery estimates.

Support

Targets (33)

Supported targets

Anchor to MethodsMethods

The shopify global object provides access to the Storefront GraphQL API. Use shopify.query() or the shopify:storefront fetch protocol to execute GraphQL queries. Available to purchase extension targets.

Anchor to query query <Data = unknown, Variables = Record<string, unknown>>(query: string, options?: { variables?: Variables; version?: ; }) => Promise<{ data?: Data; errors?: []; }> required: The method used to query the Storefront GraphQL API with a prefetched token.

StorefrontApiVersion

The supported Storefront API versions. Pass one of these values to `query()` to target a specific API version when querying the Storefront GraphQL API.

'2022-04' | '2022-07' | '2022-10' | '2023-01' | '2023-04' | '2023-07' | '2024-01' | '2024-04' | '2024-07' | '2024-10' | '2025-01' | '2025-04' | 'unstable' | '2025-07' | '2025-10'

GraphQLError

An error returned by the Storefront GraphQL API. Contains a human-readable `message` and an `extensions` object with the request ID and error code for debugging.

extensions
Additional error metadata including the request ID and error code.
```
{ requestId: string; code: string; }
```
message
A human-readable description of the error.
```
string
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useEffect, useState} from 'preact/hooks';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

const [data, setData] = useState();

useEffect(() => {

shopify

.query(

`query ($first: Int!) {

products(first: $first) {

nodes {

title

}

}`,

{

variables: {first: 5},

)

.then(({data, errors}) => setData(data))

.catch(console.error);

}, []);

return (

<s-unordered-list>

{data?.products?.nodes.map((node) => (

<s-list-item key={node.id}>

{node.title}

</s-list-item>

))}

</s-unordered-list>

);

}

Examples

Description

Load storefront data using the built-in `query()` helper. This example calls `shopify.query()` with a products query and renders the results as a list, using variables to control the number of items returned.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const [data, setData] = useState();

  useEffect(() => {
    shopify
      .query(
        `query ($first: Int!) {
        products(first: $first) {
          nodes {
            id
            title
          }
        }
      }`,
        {
          variables: {first: 5},
        },
      )
      .then(({data, errors}) => setData(data))
      .catch(console.error);
  }, []);

  return (
    <s-unordered-list>
      {data?.products?.nodes.map((node) => (
        <s-list-item key={node.id}>
          {node.title}
        </s-list-item>
      ))}
    </s-unordered-list>
  );
}

Description

Access the Storefront GraphQL API using global `fetch()` with the `shopify:storefront` protocol. This approach automatically infers your Storefront URL and uses the API version declared in `shopify.extension.toml`. You can override the version by adding it to the URL, like `shopify:storefront/api/2024-04/graphql.json`.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const [data, setData] = useState();

  useEffect(() => {
    const getProductsQuery = {
      query: `query ($first: Int!) {
        products(first: $first) {
          nodes {
            id
            title
          }
        }
      }`,
      variables: {first: 5},
    };

    fetch('shopify:storefront/api/graphql.json', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(getProductsQuery),
    })
      .then((response) => response.json())
      .then(({data, errors}) => setData(data))
      .catch(console.error);
  }, []);

  return (
    <s-unordered-list>
      {data?.products?.nodes.map((node) => (
        <s-list-item key={node.id}>
          {node.title}
        </s-list-item>
      ))}
    </s-unordered-list>
  );
}

Anchor to Best practicesBest practices

Prefer shopify.query() over raw fetch(): The query() helper handles authentication, versioning, and error formatting automatically. Use fetch() with the shopify:storefront protocol only when you need lower-level control over the request.
Minimize query complexity: Checkout extensions run in a latency-sensitive context. Request only the fields you need and avoid deeply nested queries to keep the checkout fast.
Handle loading and error states: Storefront API requests are asynchronous. The query() method returns both data and errors, and a response might contain partial data alongside errors. Show a loading indicator while data loads and display a graceful fallback if the request fails or returns errors.

Anchor to LimitationsLimitations

The Storefront API requires the api_access capability in shopify.extension.toml. Without it, shopify.query() isn't available and fetch() calls to shopify:storefront are rejected.
Storefront API rate limits apply to all queries made from checkout extensions. Heavy or frequent queries may be throttled, which can slow down the checkout experience.

Was this page helpful?