Build on Mercury
Mercury is the search and merchandising layer behind Shopify storefronts: rendered collections, search with facets and synonyms, autocomplete, recommendation zones, and a customisable collection widget. These docs cover the storefront API your theme or headless frontend calls, and the Collection Kit for changing how the grid looks and behaves.
Getting started
Base URL, regions, and authenticating with your storefront Origin or a bypass token. Your first request.
Storefront API v1
8 operations, generated from the typed contracts, with auth, quirks and examples.
Collection Kit
Replace any part of the collection grid with your own Svelte component or function.
Versions and changelog
v1 is frozen; v2 will mirror Shopify’s Storefront API. What that means for you.
Guides
Search, collections and products
The routes a collection page, a search page, an autocomplete box and a product block call, and how paging, facets, redirects and suggestions behave.
Filters and sorting
The `query` filter format the collection, search and zone routes accept, how clauses combine, the facet counts, and the sort names, including Shopify's.
Zones
Recommendation blocks the merchant configures in Mercury, rendered by one call: by zone id or by page template, with the cart's contents for cart zones.
Currencies and presentment prices
Major and minor units, the per-currency `prices` map, what `?currency=` does, and the zero-price trap.
Errors and status codes
The error envelope every route uses, what each status means on the storefront routes, and the zone answers that carry no body.
Caching and rate limits
What Mercury caches on its side, what it tells your browser (nothing, today), how fresh results are, and how hard you can call it.
Known v1 quirks
What the v1 wire actually sends where it differs from what you'd expect. v1 keeps these for compatibility; v2 fixes them.