Mercury Storefront API
Call these from a storefront (the browser sends your Origin) or from a server with ?bypassToken=. Start with getting started.
The storefront surface of Mercury: search, collections, autocomplete, zones, and the legacy product, page, collection and filter reads. v1 is today's surface and is frozen in shape: fixes keep its keys and values. v2 will mirror Shopify's Storefront API shapes. Generated from api-types/src/storefront.
8 operations, 31 schemas. Download the OpenAPI 3.1 document for code generators, Postman or Scalar.
Search, collections and products
| Path | What it does | Auth | |
|---|---|---|---|
| GET | /search/collection/{handle} | Rendered collection by handle: products, facets and merchandising for a collection page. | Storefront: Origin or bypassToken |
| GET | /search/product/{handles} | Rendered products by comma-separated handles (capped at 20; each product run through mapOutput with ?currency=). | Storefront: Origin or bypassToken |
| GET | /search/query/{term} | Full rendered search: autocomplete suggestions + faceted results. | Storefront: Origin or bypassToken |
| GET | /search/suggest/{term} | Autocomplete suggestions from the store's suggestion dictionary (redis FT.SUGGET, fuzzy). | Storefront: Origin or bypassToken |
Zones
| Path | What it does | Auth | |
|---|---|---|---|
| GET | /zone/query | Execute a zone query without an id — the zone is located via ?templateName= (or the store default). | Storefront: Origin or bypassToken |
| POST | /zone/query | Programmatic zone query without an id (template lookup, e.g. | Storefront: Origin or bypassToken |
| GET | /zone/query/{id} | Execute a zone query by zone id. | Storefront: Origin or bypassToken |
| POST | /zone/query/{id} | Programmatic zone query by id (cart contents etc. | Storefront: Origin or bypassToken |
Schemas
ApiErrorResponseConditionalZoneConditionsFilterOperatorGridConfigImplodeModeManualZoneConditionsMercurySortOrderRedisPriceEntryRedisPricesMapRedisProductRedisProductMetaRenderedBadgeRenderedCollectionRenderedProductRenderedSearchRenderedVariantRenderedZoneSearchFacetsShopifyCollectionRuleSuggestResponseTagFacetRowTypeFacetRowVendorFacetRowZoneCartLineZoneConfigZoneDefaultConditionsZoneFallbackZoneProgrammaticBodyZoneResponseZoneRuleZoneRuleGroup