--- title: Storefront API description: >- Query the Storefront GraphQL API from inside your extension to fetch products, collections, and other store data. api_version: 2026-07-rc source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/platform-apis/storefront-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/platform-apis/storefront-api.md api_name: checkout-ui-extensions --- # Storefront API **Requires the \[\`api\_access\` capability]\(/docs/api/checkout-ui-extensions/configuration#api-access) enabled in \`shopify.extension.toml\`.:** The Storefront API provides access to Shopify's [Storefront API](https://shopify.dev/docs/api/storefront) 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. ### Use 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 * [purchase.​address-autocomplete.​format-suggestion](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/address#format-a-selected-suggestion-) * [purchase.​address-autocomplete.​suggest](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/address#suggest-address-completions-) * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/header#header-target) ### Methods The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc#target-apis-define-what-your-extension-does) 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. * **query** **\>(query: string, options?: { variables?: Variables; version?: StorefrontApiVersion; }) => Promise<{ data?: Data; errors?: GraphQLError\[]; }>** **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. ```ts '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' | '2026-01' | '2026-04' | '2026-07' ``` ### 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. ```ts { requestId: string; code: string; } ``` * message A human-readable description of the error. ```ts string ``` Examples ### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useEffect, useState} from 'preact/hooks'; export default function extension() { render(, 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 ( {data?.products?.nodes.map((node) => ( {node.title} ))} ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useEffect, useState} from 'preact/hooks'; export default function extension() { render(, 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 ( {data?.products?.nodes.map((node) => ( {node.title} ))} ); } ``` *** ## Best 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. *** ## Limitations * 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. ***