The Shopify Storefront API is Shopify’s GraphQL-only API for building customer-facing, headless storefronts. Use it for product browsing, cart management, and checkout initiation, and reserve the Admin API for merchant tasks like orders and fulfillment. Authentication is the part teams

get wrong most often, so token type and the Headless channel deserve attention from day one.

TL;DR:

  • The Shopify Storefront API has a limit of 100 active tokens per shop, requiring careful management and regular cleanup across environments.
  • Tokenless access suffices for public product browsing, but customer-specific data and navigation need authenticated tokens, which must be rotated and kept secret.
  • All requests must use the correct API version header and appropriate token type, with private tokens never exposed in client-side code to maintain security.
  • A clear environment-based naming and rotation policy for tokens prevents exceeding limits and ensures smooth updates during version upgrades.
  • Most performance and security issues stem from mishandling token access, caching, and API boundaries; an architecture review is crucial before building.

Table of Contents

What the Storefront API Is and Where It Fits

The Storefront API speaks GraphQL exclusively. Every query and mutation goes to one endpoint, https://{shop}.myshopify.com/api/{version}/graphql.json, using a POST request, according to a breakdown of the Shopify developer API ecosystem. There is no REST version and no second endpoint to remember.

That single endpoint handles anything a shopper touches: product and collection lookups, search, cart creation, and checkout initiation. What it does not touch is merchant operations. Order management, inventory adjustments, and fulfillment stay on the Admin API, which is built for CRUD work rather than buyer-facing reads, per the same ecosystem overview.

This split shows up constantly in headless projects:

  • Next.js or Hydrogen storefronts pull product data through the Storefront API and hand off checkout.
  • Native mobile apps use it to render catalogs without touching the merchant back end.
  • Social and gaming integrations lean on the same read-heavy pattern for embedded shopping.

Know this boundary early and you avoid a rebuild later.

Key Features, Limits, and Common Gotchas

Not every field is open to tokenless requests. Products, collections, search, pages, blogs, and basic cart operations work without a token, within query complexity limits. Metaobjects, tags, menus and navigation, and customer account data all require an authenticated token, as Shopify’s own guidance on building with the Storefront API explains. Teams that prototype on tokenless access often hit a wall the moment a client asks for personalized navigation or saved customer data.

A shop can run a maximum of 100 active storefront access tokens at once. That sounds generous until you count preview environments, staging storefronts, and every developer’s local setup. Without a cleanup policy, teams with multiple environments hit that ceiling faster than expected.

A few other constraints worth planning around:

  • Query complexity limits apply even to tokenless requests, so deeply nested queries can get throttled.
  • Automated or bot traffic is rate-limited differently from real buyer traffic.
  • Attempting to modify an order through the Storefront API is a common anti-pattern. That job belongs to the Admin API.

Treat the 100-token limit as a budget, not an afterthought, and name tokens by environment from the start.

Authentication, Token Types, and the Headless Channel

Three access patterns cover almost every scenario. Tokenless access handles basic public reads. Public tokens are safe to ship in client-side code for storefront browsing. Private tokens are for server-side requests only and should never appear in a browser bundle.

The Headless channel is the control center for all of this. It centralizes token creation and rotation, and it ties each storefront to order attribution and channel-level analytics, according to Shopify’s getting started guide. Instead of managing tokens by hand across environments, you manage them through one channel with a consistent naming and rotation policy.

A short checklist keeps token handling sane:

  1. Never commit a private token to a repository or expose it in client-side code.
  2. Rotate tokens on a fixed schedule rather than waiting for an incident.
  3. Request only the scopes a storefront actually needs.
  4. Track token usage across environments so you see the 100-token cap coming before you hit it.

Pro Tip: Name every storefront token with its environment and purpose (prod-web, staging-mobile) so a rotation script can find and retire the right ones without guesswork.

API Versioning, Endpoints, and Request Basics

Shopify releases a new API version four times a year and recommends updating to the latest stable release each quarter, per the Storefront API reference. Falling behind by a year or more tends to mean a bigger, riskier migration later instead of four small ones.

Every request needs the right header for its token type:

  • X-Shopify-Storefront-Access-Token for public, client-safe tokens.
  • Shopify-Storefront-Private-Token for authenticated server-side requests.
  • Shopify-Storefront-Buyer-IP on server-side requests that originate from a real buyer, so Shopify can classify traffic correctly.

Where possible, use an official client like shopify.query() instead of hand-rolling requests. It handles versioning, headers, and formatting so you spend less time debugging boilerplate.

Best Practices for Secure, Maintainable Integrations

The cleanest architecture keeps buyer flows on the Storefront API and routes anything sensitive, merchant-side, or order-related through a server-side backend calling the Admin API. If your project involves custom checkout logic, our piece on Shopify checkout customization walks through where that server-side boundary should sit.

A few patterns hold up across most headless builds:

  • Edge-cache product and collection reads aggressively; they change infrequently and carry no buyer-specific state.
  • Never cache cart or checkout tokens, since they are scoped to a single buyer session.
  • Rate-limit and gate automated traffic separately from real shoppers, using Web Bot Auth or a dedicated gateway when bots need higher limits, as described in the Storefront API reference.
  • Tie token rotation to your CI/CD pipeline instead of a manual calendar reminder, and use environment-specific tokens so a staging leak never touches production.

Pro Tip: Run a quarterly audit of active storefront tokens alongside your API version upgrade. It is the easiest way to catch stale tokens before they eat into your 100-token limit.

Quick Start: Your First Storefront API Request

A minimal products query looks like a standard GraphQL POST with an access token header attached. From there, cart creation follows the same shape: a mutation instead of a query, sent to the same endpoint.

  1. Send a POST request to https://{shop}.myshopify.com/api/2026-07/graphql.json with a GraphQL query body asking for product titles and prices.
  2. Use the X-Shopify-Storefront-Access-Token header for a public, client-safe token, or Shopify-Storefront-Private-Token when the request originates from your server.
  3. Swap the query for a cartCreate mutation once you need to add items and move toward checkout.
  4. Keep private tokens in environment variables and behind a server endpoint. Never send them from a browser.

From there, the fastest way to see the shape of real responses is Shopify’s GraphiQL explorer. It lets you test queries against a live store before wiring anything into your app.

When Building In-House Stops Making Sense

Complex checkout customization, Admin API migrations, and security-sensitive token management are where most in-house teams start losing time. A proper engagement should include an architecture review, a token strategy, CI/CD integration, and a caching plan before a single line of storefront code changes. Our headless Shopify work covers what that looks like in practice.

— Chad

How Bowtie Helps You Ship a Secure Storefront

Building a Storefront API integration that holds up under real traffic takes more than a working query. It takes a token strategy that survives staff turnover, a caching layer that does not leak buyer data, and an Admin API boundary that keeps merchant operations safe. That is where we come in.

Bowtie

Bowtie runs Ecommerce Assessments and Shopify Audits starting from $299, which map your current Storefront and Admin API setup and flag token or architecture risks before they become incidents. For teams ready to build, our Shopify Theme Customization work starts from $5,000, and full Shopify Plus and bespoke Storefront builds start from $12,000. If you already have code and want a second set of eyes, a Senior Developer Review starts from $449 and covers exactly the kind of token handling and architecture questions this article raises.

A sensible starting point for most teams: begin with a Senior Developer Review or a Shopify audit, use the findings to settle your token and caching strategy, then move into a custom build with that architecture already validated. Our Shopify experts page has more on how we approach these engagements end to end.

How Bowtie Helps You Ship a Secure Storefront — overview diagram

Check current pricing and book a review at Bowtie.

Sources

FAQ

Is the Shopify API free?

Shopify’s APIs, including the Storefront API, have no separate licensing fee: access is included with a Shopify plan that supports API use. Costs come from your own development time and any paid apps or services you build around it, not from the API itself.

How do I get a storefront API access token for Shopify?

You generate a storefront access token through the Headless channel in your Shopify admin, which lets you create and manage both public and private tokens, according to Shopify’s getting started documentation. The same channel handles rotation and ties each storefront to order attribution.

Is there a REST API for Shopify?

The Storefront API is GraphQL-only, with no REST equivalent, as confirmed by a rundown of Shopify’s API ecosystem. Shopify’s Admin API has historically offered REST endpoints alongside GraphQL, though GraphQL is the direction most new development follows.

Is Shopify storefront free?

Using the Storefront API costs nothing beyond your existing Shopify plan, since it is a development tool rather than a separate paid product. What you build with it, from custom themes to full headless storefronts, is where actual costs show up, and those vary based on the scope of the project.