Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 55 ยท Storefront API and Headless

Storefront API Basics

Learn what the Shopify Storefront API is for, how public and private tokens differ, how it differs from the Admin API, and how to query products, collections and carts.

Up to now this track has talked to Shopify as the merchant's app: the Admin GraphQL API lets your server read and change everything about a shop, with an access token that must never leave your backend. The Storefront API is the other side of the coin. It is the API for the buyer: it exposes what a shopper may see (products, collections, prices, availability, a cart) and lets them build a cart and walk to checkout. It is what you use when you build a custom storefront, a mobile shopping app, or a widget that shows live products on a non-Shopify page.

This lesson explains who the Storefront API is for, the two kinds of tokens, how it differs from the Admin API, and how a typical query looks. The real requests are read-only code blocks, because they need a real shop and a real token. The runnable examples are stand-ins: a query builder and a token-choice helper. The examples target API version 2026-07; replace it with the latest stable version you use (see API Versioning and Deprecations, which applies the same quarterly rhythm to the Storefront API).

Admin API versus Storefront API

Both are GraphQL, both are versioned every quarter, and both are called with HTTP POST. The differences are about audience and safety.

Admin API Storefront API
Audience The merchant (your app acts for them) The buyer (anyone who visits the shop)
Endpoint https://{shop}.myshopify.com/admin/api/2026-07/graphql.json https://{shop}.myshopify.com/api/2026-07/graphql.json
Credential Access token with scopes, kept secret Storefront access token, public or private
Data Orders, customers, inventory, everything Only what is published to the sales channel
Costs Calculated query cost and a leaky bucket (Rate Limits) Built for high buyer traffic; no points bucket, but bot protection applies
Unpublished or draft products Visible Hidden

The Storefront API never returns private data such as other customers' orders, and it respects what the merchant has made available to the channel your token belongs to. That is why it is safe to use from a browser or phone app at all.

Public and private tokens

A Storefront API token is sent in a request header, and there are two kinds.

  • A public token goes in X-Shopify-Storefront-Access-Token. It is meant to be embedded in client code (a mobile app, a browser script). Because anyone can copy it, it must only be able to do what any visitor could do anyway. It also depends on the buyer's own IP address for rate and abuse limits, which is why it works well directly from browsers.
  • A private token goes in Shopify-Storefront-Private-Token. It is a secret that must stay on your server. Requests with it come from your server's IP address, so you should pass the shopper's address along in the Shopify-Storefront-Buyer-IP header so that protections look at the real buyer and not at your server. Use it when the storefront renders on the server, as headless frameworks do.
HTTP
POST /api/2026-07/graphql.json HTTP/1.1
Host: your-shop.myshopify.com
Content-Type: application/json
Shopify-Storefront-Private-Token: shpat_xxxxx   <- server only
Shopify-Storefront-Buyer-IP: 203.0.113.9        <- the shopper, not your server

The rule of thumb: server-rendered code uses a private token; code that runs on the buyer's device uses a public token. Never put an Admin API token anywhere near a browser, and never confuse the two, because an Admin token in public code hands over the whole shop. Access to the Storefront API is also tied to the sales channel and the permissions (called Storefront API access scopes, such as reading products or managing carts) granted when the token is created.

Reading products and collections

A product page query looks much like the Admin queries you have seen, but with buyer-facing fields. Notice that prices are objects with amount and currencyCode, and that availableForSale replaces inventory counts.

GRAPHQL
# read-only: needs a real shop and token
query ProductByHandle($handle: String!) {
  product(handle: $handle) {
    id
    title
    description
    featuredImage { url altText }
    priceRange {
      minVariantPrice { amount currencyCode }
    }
    variants(first: 10) {
      nodes {
        id
        title
        availableForSale
        price { amount currencyCode }
      }
    }
  }
}

Storefront objects are found by handle (the URL slug, such as blue-tshirt) as often as by global ID. Collections work the same way, and products can be filtered and sorted:

GRAPHQL
query CollectionPage($handle: String!, $after: String) {
  collection(handle: $handle) {
    title
    products(first: 12, after: $after, sortKey: PRICE) {
      nodes { id title handle priceRange { minVariantPrice { amount currencyCode } } }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Pagination works exactly as described in Pagination with Cursors: first, after, pageInfo.

Context: market, country and language

Prices and availability depend on where the buyer is. The Storefront API lets you set that with the @inContext directive on the operation, for example query Products @inContext(country: DE, language: DE) { ... }. Without it, you get the shop's default market. This is the basis of international storefronts; the money and localization theory is in Currencies and Localization.

The cart

Where the Admin API would create a draft order, the Storefront API offers a cart object. You create one, add lines, optionally attach buyer details and discount codes, and then send the shopper to the cart's checkoutUrl, where Shopify's own checkout takes over. The next lesson, Building a Cart with the Storefront API, covers the mutations in depth. Here is just the shape of a cart read:

GRAPHQL
query GetCart($id: ID!) {
  cart(id: $id) {
    id
    checkoutUrl
    totalQuantity
    cost { subtotalAmount { amount currencyCode } totalAmount { amount currencyCode } }
    lines(first: 50) {
      nodes { id quantity merchandise { ... on ProductVariant { id title } } }
    }
  }
}

The ... on ProductVariant part is an inline fragment: a cart line's merchandise could in principle be several types, so you say which fields you want when it is a variant.

A query builder stand-in

Writing long GraphQL strings by hand is error-prone, and apps usually build them from field lists. This stand-in builds the cart query above from a list of options, indents it correctly and reports a rough depth. It does not call Shopify; it only shows how a query is assembled.

JS Build a cart query from options

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Choosing the right token

The decision between public and private tokens is simple, but it is also where beginners make costly mistakes. This stand-in turns the rule of thumb into code so you can see how it behaves. The header names are the real ones; the function is only a helper for this lesson.

JS Which token and header should this call use?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

flowchart LR
    B["Buyer's browser or app"] -->|"public token"| SF["Storefront API"]
    S["Your server (SSR)"] -->|"private token + buyer IP"| SF
    A["Your app backend"] -->|"Admin token"| AD["Admin API"]
    SF --> C["Cart and checkoutUrl"]
    C --> CO["Shopify checkout"]

Buyers and storefront servers use the Storefront API; the Admin API stays on the backend.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Who is the Storefront API designed for?

    The Storefront API is the buyer-facing API. It exposes products, collections, prices, availability and carts, and hides orders, customers and unpublished data.
  2. 2. Where must a private Storefront token be used?

    A private token is a secret. Requests come from your server, so you forward the shopper's address in Shopify-Storefront-Buyer-IP so protections see the real buyer.
  3. 3. Which header carries a public Storefront token?

    Public tokens use X-Shopify-Storefront-Access-Token. X-Shopify-Access-Token is the Admin API header, and the private header is a different name.
  4. 4. How does a Storefront price differ from an Admin inventory view?

    Buyers need to know whether they can buy and what it costs, so the API exposes availability and money objects rather than internal stock counts.

Summary

  • The Storefront API is the buyer-facing GraphQL API at /api/{version}/graphql.json; the Admin API stays on your backend.
  • Public tokens (X-Shopify-Storefront-Access-Token) may live in client code; private tokens (Shopify-Storefront-Private-Token) stay on the server and need the buyer IP forwarded.
  • Products and collections are usually fetched by handle, prices are money objects, and @inContext sets country and language.
  • A cart carries the shopper to the checkoutUrl, where Shopify's checkout takes over.

Next: Building a Cart with the Storefront API.