Versions and changelog
v1 is frozen in shape; v2 will mirror Shopify's Storefront API. How versions are kept, and what has changed.
The versions
| Version | Status | What it is |
|---|---|---|
| Storefront API v1 | Current, frozen in shape | Today's surface: the reference. Keys and values stay as they are, quirks included. Fixes that would change a response's shape don't ship in v1. |
| Storefront API v2 | Planned | A clean surface that mirrors Shopify's Storefront API: products and collections with edges/nodes and cursor paging, priceRange { minVariantPrice { amount currencyCode } }, GIDs as ids, camelCase, one envelope and one error shape. REST paths, every route served from Redis in every region. |
| Collection Kit contract v1 | Supported, frozen | What published kit bundles read: the contract. See contract versions. |
How v1 is kept stable
The v1 reference is generated from the contracts in api-types/src/storefront, and CI holds the server to
them: every contract must be a registered route, every storefront route must have a contract, and every
handler's response type must satisfy its contract. The published OpenAPI documents are regenerated from
the same contracts, and CI fails if they drift. A change to v1's shape therefore shows up as a contract
change in review, not as a surprise in production.
When v1 moves behind the new view service, its responses will be checked against the current ones with a live shadow comparison before any traffic moves: same keys, same values.
How v2 will arrive
v2 will have its own contracts in api-types, its own generated reference (next to v1 in this site's
navigation) and its own paths, so v1 and v2 run side by side. Once released, a v2 contract is frozen the
way kit contracts are: additions are fine, changes and removals mean v3. v1 keeps working for as long as
storefronts call it.
Until v2 lands, write new code against v1 with the quirks in mind, and keep the mapping from Mercury's shapes to your own in one place; that is the code v2 will simplify.
Changelog
Changes that matter to storefront developers, newest first.
2026-11
- Developer docs. This site: the storefront reference generated from the contracts, with each route's auth, URL and status read from the server's own route metadata.
- The public reference covers the canonical client routes only: collections, search, suggestions, products by handle and zones. Older and internal paths are left out.
2026-09
- Search tolerates typos in titles, in the same query rather than as a zero-result fallback.
- Collection Kit
priceCeiling: a price slider's range no longer shrinks when a price filter is applied.