Introduction to Shopify's Storefront GraphQL

Shopify’s Storefront API provides the commerce layer for custom storefronts, mobile applications, product-discovery experiences, and other buyer-facing sales channels.

Instead of relying on Shopify’s Liquid theme system, developers can use the API to retrieve products and collections, perform searches, create carts, apply discounts, support international pricing, and direct customers to Shopify’s secure checkout.

The Storefront API uses GraphQL exclusively. A storefront requests the specific fields it needs, and Shopify returns data matching that request. This can make commerce integrations more predictable and efficient than retrieving large, fixed responses.

However, GraphQL does not make a storefront fast, secure, or maintainable automatically. Those outcomes still depend on query design, rendering strategy, authentication, caching, error handling, and API-version management.

What Is Shopify’s Storefront API?

The Storefront API is Shopify’s buyer-facing commerce API.

It gives custom storefronts access to published commerce data without exposing administrative store functionality. Developers can use it to build experiences with frameworks such as React, Next.js, Remix, Vue, Nuxt, SvelteKit, or Shopify’s Hydrogen framework.

Common Storefront API capabilities include:

• Retrieving products, variants, collections, pages, blogs, and articles
• Searching and filtering the product catalogue
• Displaying contextual prices and availability
• Reading menus, metafields, and metaobjects when authorized
• Creating and managing carts
• Applying discount codes and gift cards
• Associating buyer information with a cart
• Sending the customer to Shopify-hosted checkout

The API is designed for sales channels used by shoppers. It is not intended for changing product records, fulfilling orders, managing inventory, or performing other administrative work.

Storefront API vs Admin API vs Customer Account API

Shopify provides different GraphQL APIs for different responsibilities.

A headless storefront may use more than one of these APIs, but they should normally be accessed through separate integration layers.

For example, a product page can retrieve published product information through the Storefront API. An order-management service can update fulfilment data through the Admin API. An authenticated account area can retrieve the customer’s order history through the Customer Account API.

An Admin API token must never be exposed in storefront JavaScript. It provides privileged access and belongs only in a secure server-side environment.

How GraphQL Works

GraphQL allows an application to describe the structure of the response it needs.

A REST endpoint might return a predetermined product representation containing many fields. A GraphQL query can request only the product title, featured image, price, and available variants required by a particular component.

For example:

query ProductByHandle($handle: String!) {
  product(handle: $handle) {
    id
    handle
    title
    description
    featuredImage {
      url
      altText
      width
      height
    }
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
    variants(first: 10) {
      nodes {
        id
        title
        availableForSale
        price {
          amount
          currencyCode
        }
      }
    }
  }
}

Variables are submitted separately:

{
  "handle": "trail-running-shoe"
}

This separation makes queries easier to reuse and prevents developers from constructing GraphQL documents through unsafe string concatenation.

The response follows the shape of the query:

{
  "data": {
    "product": {
      "id": "gid://shopify/Product/1234567890",
      "handle": "trail-running-shoe",
      "title": "Trail Running Shoe",
      "description": "A lightweight shoe designed for mixed terrain.",
      "featuredImage": {
        "url": "https://cdn.shopify.com/...",
        "altText": "Black trail running shoe",
        "width": 1600,
        "height": 1600
      },
      "priceRange": {
        "minVariantPrice": {
          "amount": "129.00",
          "currencyCode": "USD"
        }
      },
      "variants": {
        "nodes": [
          {
            "id": "gid://shopify/ProductVariant/9876543210",
            "title": "Black / 9",
            "availableForSale": true,
            "price": {
              "amount": "129.00",
              "currencyCode": "USD"
            }
          }
        ]
      }
    }
  }
}

Shopify uses global IDs such as gid://shopify/Product/1234567890 to identify objects. Applications should treat these values as opaque identifiers rather than extracting and depending on their numeric portions.

Storefront API Endpoint and Versioning

Storefront API requests use a versioned GraphQL endpoint:

https://{store-name}.myshopify.com/api/{api-version}/graphql.json

A request might therefore target an endpoint such as:

https://example-store.myshopify.com/api/2026-04/graphql.json

Shopify publishes API versions four times per year. Each application should specify a supported version instead of depending on automatic fallback behaviour.

Before upgrading, review Shopify’s developer changelog, test queries against the new schema, and confirm that deprecated fields have been replaced. Version upgrades are particularly important for long-running headless storefronts because a removed field can affect product pages, carts, search, or checkout entry points.

The Storefront API reference provides the schema, available versions, arguments, return types, and examples.

Storefront API Authentication

Shopify supports tokenless and token-based Storefront API access.

Tokenless access covers several essential capabilities, including products, collections, content, search, selling plans, and carts. Other features, such as menus, customer-related operations, product tags, metafields, and metaobjects, require an access token.

For token-based access, Shopify supports public and private Storefront access tokens.

Public Access Tokens

A public access token is intended for environments where its value can be inspected, including:

• Browser-based storefronts
• Mobile applications
• Public client-side JavaScript

The token is passed using this header:

X-Shopify-Storefront-Access-Token: PUBLIC_STOREFRONT_TOKEN

Calling a token “public” does not mean it should receive unnecessary permissions. Grant only the Storefront API access scopes required by the experience.

Private Access Tokens

A private Storefront access token is designed for servers and other trusted environments.

It is passed using:

Shopify-Storefront-Private-Token: PRIVATE_STOREFRONT_TOKEN

When a server-side request is made on behalf of a shopper, Shopify also instructs applications to include the buyer’s IP address using the case-sensitive Shopify-Storefront-Buyer-IP header.

Private Storefront tokens must not be delivered to browsers, embedded in mobile application bundles, committed to Git, or exposed through public environment variables.

Shopify’s API authentication documentation explains the current public, private, and tokenless access models.

Making a Storefront API Request

The following JavaScript example sends a product query using a public Storefront token:

const endpoint =
  "https://example-store.myshopify.com/api/2026-04/graphql.json";

const query = `
  query ProductByHandle($handle: String!) {
    product(handle: $handle) {
      id
      title
      handle
      featuredImage {
        url
        altText
      }
      priceRange {
        minVariantPrice {
          amount
          currencyCode
        }
      }
    }
  }
`;

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Shopify-Storefront-Access-Token":
      process.env.PUBLIC_STOREFRONT_TOKEN
  },
  body: JSON.stringify({
    query,
    variables: {
      handle: "trail-running-shoe"
    }
  })
});

const result = await response.json();

if (!response.ok) {
  throw new Error(`Storefront request failed: ${response.status}`);
}

if (result.errors?.length) {
  throw new Error(result.errors.map((error) => error.message).join(", "));
}

const product = result.data.product;

The exact environment-variable mechanism depends on the framework. Developers should verify whether a framework exposes variables to the browser before placing any credential in them.

Retrieving Product Lists With Pagination

Shopify product and collection lists use cursor-based pagination.

A query requests the first set of results and receives a cursor representing the end of that page:

query Products($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    nodes {
      id
      handle
      title
      featuredImage {
        url
        altText
      }
      priceRange {
        minVariantPrice {
          amount
          currencyCode
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Example variables for the first request:

{
  "first": 20,
  "after": null
}

If hasNextPage is true, the next request sends the returned endCursor as after.

Cursor pagination is more suitable for an evolving catalogue than calculating page offsets. Products can be added, removed, or reordered without the application depending on fixed numerical positions.

Avoid requesting hundreds of products and deeply nested variants in one query merely because GraphQL permits nesting. Smaller queries are easier to cache, render, retry, and diagnose.

Reusing Fields With GraphQL Fragments

Fragments reduce duplication when several queries need the same fields.

fragment ProductCardFields on Product {
  id
  handle
  title
  featuredImage {
    url
    altText
  }
  priceRange {
    minVariantPrice {
      amount
      currencyCode
    }
  }
}

query FeaturedProducts {
  products(first: 8) {
    nodes {
      ...ProductCardFields
    }
  }
}

Fragments work especially well with component-based storefronts. A product-card fragment can represent the data contract required by a product-card component.

However, fragments should not become an excuse to request every possible product field. A large universal fragment can silently make lightweight pages more expensive and slower.

Creating a Cart

Shopify’s current Storefront API uses the Cart API.

Older integrations may contain operations such as checkoutCreate or checkoutLineItemsUpdate. These belong to Shopify’s retired Checkout API workflow and should not be used for new Storefront API implementations.

A cart can be created with one or more product variants:

mutation CreateCart($input: CartInput) {
  cartCreate(input: $input) {
    cart {
      id
      totalQuantity
      checkoutUrl
      lines(first: 20) {
        nodes {
          id
          quantity
          merchandise {
            ... on ProductVariant {
              id
              title
              product {
                title
                handle
              }
              price {
                amount
                currencyCode
              }
            }
          }
        }
      }
      cost {
        subtotalAmount {
          amount
          currencyCode
        }
        totalAmount {
          amount
          currencyCode
        }
      }
    }
    userErrors {
      field
      message
      code
    }
    warnings {
      message
      code
    }
  }
}

Variables use a product variant ID as the merchandise ID:

{
  "input": {
    "lines": [
      {
        "merchandiseId": "gid://shopify/ProductVariant/9876543210",
        "quantity": 1
      }
    ]
  }
}

The returned cart ID should be stored for the buyer’s session. Subsequent operations can use:

• cartLinesAdd
• cartLinesUpdate
• cartLinesRemove
• cartBuyerIdentityUpdate
• cartDiscountCodesUpdate
• cartGiftCardCodesAdd

When the customer is ready to purchase, the storefront redirects them to the cart’s checkoutUrl. Shopify then handles the checkout experience and its supported payment, delivery, tax, and validation processes.

The current cartCreate documentation confirms that the returned cart includes the checkout URL.

Supporting Markets and International Customers

The Storefront API can return contextual data based on the shopper’s country and language.

A query can use the @inContext directive:

query ProductForMarket(
  $handle: String!
  $country: CountryCode!
  $language: LanguageCode!
) @inContext(country: $country, language: $language) {
  product(handle: $handle) {
    title
    description
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
  }
}

The country context can affect prices, currencies, availability, and other market-specific behaviour. Language context can return translated content when translations exist.

Cart buyer identity should also be set accurately because the buyer’s country helps Shopify determine international pricing. The cart context and displayed product context should agree; otherwise, customers may see one price while browsing and another after entering checkout.

Handling Errors Correctly

A successful HTTP response does not always mean every GraphQL operation succeeded.

Storefront integrations should account for several error layers.

A network or HTTP error means the request could not be completed normally. Examples include connection failures, invalid endpoints, temporary platform errors, or rejected requests.

Top-level GraphQL errors appear in the response’s errors array. These can result from invalid fields, incorrect argument types, authorization problems, or query-execution failures.

Mutation-specific business errors generally appear in userErrors. A cart mutation may return errors for an invalid merchandise ID, unavailable quantity, or malformed input.

Some cart mutations also return warnings. A warning may indicate that Shopify adjusted an operation even though the mutation produced a cart.

GraphQL can return partial data alongside errors. Applications should therefore inspect both data and errors instead of assuming that one always excludes the other.

Customer-facing messages should remain useful and non-technical. Detailed GraphQL responses can be captured in secure application logs, but access tokens, personal information, and payment-related data should not be logged.

Performance and Caching

GraphQL reduces over-fetching only when queries are written carefully.

A product-grid query should not retrieve complete descriptions, every image, all variants, metafields, selling plans, and recommendations if the interface displays only a title, image, and starting price.

Catalogue data can often be cached because it is shared across visitors. Product descriptions, collection content, menu structures, and editorial pages are common candidates.

Cart and customer data require different treatment. They are specific to a shopper and should not be placed in a shared public cache.

A practical performance strategy includes:

• Requesting fields according to component requirements
• Paginating large connections
• Avoiding unnecessary nested collections
• Serving correctly sized Shopify CDN images
• Caching public catalogue responses appropriately
• Revalidating content when commerce data changes
• Keeping personalized cart and customer responses private
• Monitoring real storefront performance rather than query duration alone

Hydrogen includes Storefront API clients and caching patterns designed for Shopify commerce. Other frameworks can achieve similar results, but the team must establish its own request, cache, and revalidation rules.

Does the Storefront API Have Rate Limits?

Shopify’s general API-limit table lists no standard request-based or calculated-query-cost rate limit for token-based Storefront API access.

That does not mean applications should send unlimited or wasteful traffic. Shopify can apply protective measures to preserve platform stability, and tokenless queries have a complexity limit. Specific commerce operations may also have their own restrictions.

Applications should still:

• Avoid duplicate requests
• Cache suitable public data
• Use pagination
• Implement timeouts
• Retry temporary failures with controlled backoff
• Prevent automated cart abuse
• Handle unexpected throttling or service responses gracefully

The current limits should be checked in Shopify’s API limits documentation when designing traffic-intensive experiences.

What the Storefront API Cannot Do

The Storefront API is not a replacement for every Shopify integration.

It cannot be used as a general administrative interface for creating products, changing inventory, fulfilling orders, or accessing unrestricted store information. Those operations belong in an authenticated Admin API application.

It also does not provide a general GraphQL subscription system for continuously pushing every catalogue or order change to a browser.

When a backend needs to react to store changes, an application can receive appropriate Shopify webhooks, update its own systems, and revalidate affected storefront content. A storefront may also refetch information when a page becomes active or when fresh availability is commercially important.

Customer-account functionality should use Shopify’s current customer-account architecture rather than assuming the Storefront API alone covers every authenticated account requirement.

Storefront API Development Tools

Shopify provides a GraphiQL explorer for examining the Storefront schema and testing operations.

To run queries against store data, developers can install Shopify’s GraphiQL application and configure the required Storefront API access scopes. This is safer and more practical than assuming the production GraphQL endpoint automatically provides an interactive browser playground.

The API reference also provides field documentation, argument definitions, return types, examples, and version selectors.

For production development, teams may additionally use:

• GraphQL code generation
• TypeScript types
• Query linting
• Automated schema validation
• Integration tests
• Mock Storefront API responses
• Request tracing and structured logs

Generated types are particularly valuable because they reveal when a query result may be nullable and reduce assumptions about the response structure.

Common Storefront API Mistakes

One common mistake is confusing Storefront API access scopes with Admin API scopes. Storefront operations should receive only the unauthenticated Storefront scopes needed by the buyer experience.

Another is copying old Checkout API tutorials. New implementations should use cartCreate and the related Cart mutations, then redirect customers through checkoutUrl.

Developers also sometimes request product fields that do not exist. Shopify products use fields such as title, description, priceRange, and variants; they do not expose a generic top-level name and price combination.

Large nested queries can also create performance problems. GraphQL allows a developer to retrieve products, variants, images, metafields, collections, and selling plans together, but the interface rarely needs all that information simultaneously.

Finally, a headless storefront can lose functionality that a Shopify theme previously supplied automatically. SEO metadata, structured data, canonical URLs, localization, analytics, consent, accessibility, caching, and error recovery all become implementation responsibilities.

When to Use the Storefront API

The Storefront API is a suitable foundation when a business needs:

• A custom headless Shopify storefront
• A native mobile shopping application
• Commerce inside an existing content platform
• Product displays in a web application
• A specialized search or product-discovery interface
• Market-specific shopping experiences
• A frontend that combines Shopify with external services

A conventional Shopify theme may still be the better choice when the store’s requirements fit the theme system and the business does not need to maintain a separate frontend application.

Headless architecture offers more control, but that control carries additional development, monitoring, hosting, integration, and upgrade responsibilities.

Frequently Asked Questions

What is Shopify’s Storefront GraphQL API?

Shopify’s Storefront API is a buyer-facing GraphQL API for retrieving published commerce data, searching products, creating carts, supporting localization, and directing customers to Shopify’s hosted checkout.

Is the Storefront API the same as Shopify’s Admin API?

No. The Storefront API powers customer-facing experiences, while the Admin GraphQL API handles privileged operations such as managing products, inventory, orders, fulfilment, applications, and store configuration.

Can I use the Storefront API without an access token?

Yes, selected operations support tokenless access, including essential product, collection, content, search, selling-plan, and cart capabilities. Menus, metafields, metaobjects, tags, and customer features require token-based access.

Can a public Storefront token be exposed in a browser?

Yes. Public Storefront tokens are designed for browser and mobile contexts. Private Storefront tokens and Admin API tokens are secrets and must remain in protected server-side environments.

How do customers complete checkout from a custom storefront?

Create and update a cart through the Cart API, then redirect the customer to the returned checkoutUrl. Shopify handles the supported checkout, payment, delivery, tax, and validation flow.

Does the Storefront API provide real-time GraphQL subscriptions?

No general subscription interface is provided for storefront data. Applications can use Shopify webhooks in their backend, cache revalidation, and selective client refetching to keep relevant information current.

Conclusion

Shopify’s Storefront API gives developers a flexible GraphQL interface for building buyer-facing commerce experiences around Shopify’s product, market, cart, and checkout capabilities.

Its main advantage is control. A storefront can request precisely structured product data, create tailored discovery journeys, support multiple markets, integrate external content, and present a fully custom interface.

That flexibility also transfers responsibility to the development team. Queries must be accurate, tokens must be handled according to their access model, carts must use the current API, public and private data need different caching strategies, and API versions must be maintained.

The strongest implementations begin with a small, well-defined schema of storefront requirements. They request only the data each interface needs, preserve Shopify as the authority for commerce calculations, and expand the architecture only when the customer experience justifies it.

Businesses planning a custom commerce experience can work with experienced Headless Shopify developers to design the API, rendering, caching, checkout, and integration layers around measurable operational requirements.