Choose a version:

Storefront API

The Storefront API lets you query the GraphQL Storefront API to read product, collection, and other storefront data from within your extension. Use this API to display product recommendations, look up collection details, or fetch any publicly available storefront information.

This API requires the api_access capability. Enable it under [extensions.capabilities] in your extension's configuration.

For customer and order data, use the Customer Account API.

Anchor to Use casesUse cases

Display product recommendations: Query products by collection or tag and render personalized suggestions on customer account pages.
Show order-related products: Fetch product details for items in a customer's order to display warranty information, care instructions, or upsell opportunities.
Build collection browsers: Query collections to let customers browse and save products directly from a full-page extension.
Enrich extension content with storefront data: Pull product images, descriptions, and pricing to create rich, data-driven extension experiences.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the query interface for the GraphQL Storefront API. Access the following properties on shopify to fetch product, collection, and other storefront data.

Anchor to query query <Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: ; }) => Promise<{ data?: Data; errors?: []; }> required: Queries the Storefront GraphQL API directly from your extension using a prefetched token. Use this to fetch product data, collection details, or other storefront information without routing requests through your app backend.

Requires the api_access capability.

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 async () => {

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);

}, [setData]);

return (

<s-unordered-list>

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

return (

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

{node.title}

</s-list-item>

);

})}

</s-unordered-list>

);

}

Examples

Description

Use the `shopify.query()` helper to run a Storefront GraphQL query with variables. This example fetches the first five products and renders their titles in a list.

jsx

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

export default async () => {
  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);
  }, [setData]);

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

Description

Use the global `fetch()` function to query the GraphQL Storefront API directly. This example fetches products using a POST request and renders the results.

jsx

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

export default async () => {
  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},
    };

    const apiVersion = 'unstable';

    fetch(
      `shopify://storefront/api/${apiVersion}/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>
  );
}

Description

Pass a product ID as a variable to fetch details for a specific product. This example queries a single product and displays its title and description.

jsx

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

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

function Extension() {
  const [data, setData] = useState<any>(null);

  useEffect(() => {
    shopify
      .query(
        `query ($id: ID!) {
        product(id: $id) {
          title
          description
        }
      }`,
        {
          variables: {
            id: 'gid://shopify/Product/1',
          },
        },
      )
      .then(({data}) => {
        setData(data);
      })
      .catch(console.error);
  }, []);

  if (!data?.product) {
    return <s-spinner />;
  }

  return (
    <s-stack direction="block" gap="base">
      <s-heading>
        {data.product.title}
      </s-heading>
      <s-text>
        {data.product.description}
      </s-text>
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Prefer shopify.query() over raw fetch(): The query helper automatically handles GraphQL Storefront API authentication, versioning, and request formatting. Use fetch() only when you need lower-level control over the request.
Request only the fields you need: Write targeted GraphQL queries that select specific fields rather than requesting entire objects. This reduces response size and improves extension performance.
Cache responses when appropriate: If you're querying data that doesn't change frequently (such as collection metadata), store the result in component state to avoid redundant network requests on re-renders.
Handle errors and loading states: Always check for errors in the GraphQL response and display appropriate loading indicators while queries are in flight.

Anchor to LimitationsLimitations

Query complexity and rate limits from the GraphQL Storefront API still apply. Extensions that issue many concurrent queries may be throttled.

Was this page helpful?