Storefront API

Why it matters

The Storefront API is what makes Shopify a commerce backend rather than only a website builder. Anything that needs to sell without rendering a Liquid theme — a custom storefront, a mobile app, a kiosk, an in-game shop, a marketplace listing — talks to this API.

Its design decision worth understanding is the security model. Tokens are scoped to read-only storefront data and are meant to be public, which is why the API can be called straight from a browser without a server in between. That is deliberate: exposing a Storefront token is not a breach, exposing an Admin API token is.

Cart and checkout are the exception to read-only. The API can create and mutate carts, because that is a customer action rather than a store change.

How it works on Shopify

It is GraphQL, so a client asks for exactly the fields it needs and receives that shape back. For a product page, that means one round trip instead of a chain of REST calls, and no over-fetching of fields the page will not render.

Access is granted through a storefront access token, created via a custom app in the admin or issued automatically in a Hydrogen project. Public tokens suit browser clients; a private token with wider scope exists for server-side use.

Rate limiting is cost-based rather than request-based: every query has a computed cost, and you draw from a bucket that refills over time. A deeply nested query costs more than a shallow one, so query design and rate limiting are the same problem.

Metafields and metaobjects are available here only when their definitions are marked storefront-visible — the single most common source of "it works in the theme and not in the app".

Versions are dated and supported for a fixed window, so an integration needs a scheduled upgrade rather than a one-off build.

Common mistakes

• Confusing the two APIs. Reaching for the Admin API because a field is missing from the Storefront API puts a privileged token where a public one belongs.
• Over-nesting queries. Products → variants → metafields → references in one call is expensive and throttles under load. Split it.
• No caching. Catalogue data changes rarely and is requested constantly. Uncached queries make a storefront both slow and rate-limited.
• Ignoring pagination. Collections return cursors, not everything. Code that assumes the first page is the whole set breaks as the catalogue grows.
• Pinning a version and forgetting it. Unsupported versions stop working. The upgrade is small if scheduled and disruptive if discovered.

When you need help

The work worth outside input is the data layer of a custom storefront: query shape, caching strategy, and how cart state is held. Those choices decide the storefront's speed and are difficult to change once every route depends on them.

The second case is any integration that needs both APIs — a storefront reading through Storefront and a backend writing through Admin. Deciding which system owns which field, and keeping the two from contradicting each other, is the same ownership problem that sinks ERP integrations, and it is worth designing before it is written.