Storefront API caching: what can go stale and what cannot

The first thing to get straight is that there are two caches, they are configured separately, and getting one right does not save you from the other.

Sub-request caching is the response to an individual Storefront API query — the product query, the collection query, the menu query. In Hydrogen this is the cache option on the query, and the documented default when you omit it is public, max-age=1, stale-while-revalidate=86399: revalidate after a second, serve stale for up to a day. That default matters more than it looks, because a developer who has never passed a cache option has not opted out of caching. They have opted into a day of stale-while-revalidate without noticing.

Full-page caching is the rendered HTML, stored by Oxygen or whatever shared cache sits in front of your app, controlled by the Cache-Control header on the loader response. This is the layer that leaks. A page can be assembled entirely from correctly-uncached sub-requests and still be stored by a CDN with one customer's name in it, because the HTML carried a cacheable header.

So the rule is: decide per query, then decide again for the page. A route that renders anything personal needs both CacheNone() on the personal queries and a response header that keeps the HTML out of shared caches.

Product titles, descriptions, images, collection membership, navigation, metafield content, and anything coming out of a CMS: cache these hard. Hydrogen's CacheLong() is documented as public, max-age=3600, stale-while-revalidate=82800 — an hour fresh, then served stale for the next twenty-three while it refreshes behind the request.

Stale-while-revalidate is the mechanism that makes headless commerce feel fast, and it is worth understanding rather than copying. Within the max-age window the cached response is served outright. After it, the cached response is still served immediately, and the refresh happens in the background so the next visitor gets the new one. Nobody waits for Shopify. The cost is that one visitor sees content up to stale-while-revalidate seconds old, and for a product description that is not a cost at all.

The instinct to lower these numbers "to be safe" is the most common way a headless storefront ends up slower than the theme it replaced. A merchandiser edits a description twice a month. Caching it for sixty seconds to protect against that is paying for freshness nobody will ever observe.

Shopify documents that Customer Account API data is never cached by Hydrogen. That is a useful floor, and it is not the whole risk. Storefront API queries that return personalised data — the customer object, cart state — are yours to protect: CacheNone() at the sub-request level, and a Cache-Control header on the page that stops a shared cache storing the HTML.

The documented headers are the ones to learn. no-store means nobody stores this, anywhere. private, max-age=<seconds> means the buyer's own browser may keep it but shared caches may not — which is the right answer for a logged-in page that is safe to reuse on a back button and catastrophic to reuse across users.

The specific bug worth guarding against is boring and severe. Somebody adds a small personalised element — a name in the header, a loyalty balance, a cart count rendered server-side — to a route that was previously anonymous and cached at the page level. Nothing errors. The page renders correctly for the person who warmed the cache, and then serves them to everyone else. It will not appear in tests, because tests do not usually run two different users through the same shared cache. It appears in a support ticket.

The cheap defence is a rule rather than vigilance: personalised data renders on the client, or its route is never page-cached. Pick one per route and write it down next to the route.

A TTL answers "how long may this be wrong". It does not answer "make this right now", and every store eventually needs the second one — a mispriced product, a corrected description, a sale that starts at nine.

The mechanism is webhooks. Subscribe to product and inventory updates, and let the handler purge or re-warm the affected keys rather than waiting for expiry. This lets you set genuinely long TTLs, which is the point: long TTL plus event-driven invalidation gives you both speed and correctness, whereas short TTL gives you neither properly.

Two things to get right. Webhook delivery is not guaranteed to be instant or ordered, so treat invalidation as a fast path and the TTL as the backstop — never delete the TTL because the webhook exists. And make the purge granular: purging everything on every product update turns a busy merchandising afternoon into a cold cache and a stampede on Shopify.

A common justification for aggressive caching is fear of throttling, and on the Storefront API that fear is mostly misplaced. Shopify states that requests from real buyers are not subject to a fixed request-per-minute limit; the limits documented for the Storefront API concern bots and crawlers, and a per-minute throttle on checkout creation. Public access tokens are described as scaling with the number of buyers based on their IP address.

That last detail has a caching consequence people miss. If you query from a server with a private access token, every request appears to come from your server rather than from a buyer. Shopify documents the Shopify-Storefront-Buyer-IP header for exactly this, and warns that without it Shopify cannot differentiate requests from different buyers, which can result in throttled requests. If a headless storefront starts throttling under load, check that header before you touch a TTL.

So cache for the two reasons that hold: latency, because a cached response is tens of milliseconds and a round trip to Shopify is not, and resilience, because a stale-while-revalidate cache keeps serving pages through an upstream wobble. Both are good reasons. Rate limits are not the one.

• Headless Shopify development
• Do you actually need headless Shopify?
• Headless CMS choices for a Shopify storefront