Programmatic zone query by id (cart contents etc.

POST /zone/query/{id}

POST https://mercury.plutocracy.io/zone/query/{id}

Served from Redis in all four regions (Sydney, N. Virginia, N. California, Frankfurt); DNS latency routing picks the nearest.

Programmatic zone query by id (cart contents etc. in the body).

Auth: Origin+bypass redis strategy.

Responds 201 (Nest default for POST) with the same payload semantics as ZoneQueryByIdRoute.

Authentication

Send the storefront's Origin (browsers do this for you) or ?bypassToken=. A request with neither gets 401. See authentication.

Parameters

Name	In	Type	Description
`id` required	path	string
`templateName`	query	string	Template used to locate a zone when no `:id` is given (or the id misses): `cart` \| `collection` \| `product` \| `cms` \| `index` \| `wishlist`; any other value falls back to the first zone in the store's index.
`tracking`	query	string	`none` disables analytics tracking for this request.
`userId`	query	string	Client user id used to key the analytics entry.
`currency`	query	string	Narrow rendered product `prices` maps to this currency.
`query`	query	string	JSON-stringified filter operator array applied to the zone query.

Request body

Type: ZoneProgrammaticBody

Programmatic zone body (POST variant). Only lines is read (cart zones); everything else passes through untouched.

Field	Type	Description
`lines` optional	ZoneCartLine[]
`[key: string]`	any	Any further keys.

Responses

201 Created (Nest answers POST with 201). application/json

Type: ZoneResponse

Zone endpoint wire response: a rendered zone, the fallback shape, or an EMPTY body (the handler returns undefined when the matched rule group is empty).

Example response (illustrative)

{
  "deletedDate": "2026-11-01T00:00:00.000Z",
  "storeId": "7712345678901",
  "id": "7712345678901",
  "title": "Linen shirt",
  "subtitle": "Linen shirt",
  "shortcode": "string",
  "default": false,
  "area": "cart",
  "mode": "manual",
  "submode": "collection",
  "conditions": {},
  "config": {
    "allowDiscountedProducts": false,
    "allowOutOfStock": false,
    "implode": false
  },
  "appearance": "grid",
  "products": [
    {
      "id": "7712345678901",
      "title": "Linen shirt",
      "implode": 1,
      "handle": "linen-shirt",
      "vendor": "Mercury Apparel",
      "type": "Shirts",
      "on_sale": false,
      "total_stock": 12,
      "variants": [
        {
          "title": "Linen shirt",
          "id": 7712345678901,
          "inventory": 12,
          "price": "89.00",
          "compare_at_price": "89.00"
        }
      ],
      "prices": {
        "AUD": {
          "price": 89
        }
      },
      "created_date": "2026-11-01T00:00:00.000Z",
      "tags": [
        "summer"
      ]
    }
  ]
}

401 No valid credential. application/json

Type: ApiErrorResponse

default An error, in the standard envelope. application/json

Type: ApiErrorResponse

Errors use the standard envelope; see errors and status codes.

Example request

curl -X POST "https://mercury.plutocracy.io/zone/query/7712345678901?bypassToken=$MERCURY_BYPASS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"lines":[{"handle":"linen-shirt"}]}'

Where this comes from

Contract: ZoneProgrammaticQueryByIdRoute in api-types/src/storefront/zone.ts
Route: POST /zone/query/:id on the view app