PlutocracyMercury developer docs

Getting started

Where the storefront API lives, how a request proves which store it is for, and your first call.

Mercury's storefront API answers the questions a collection page, a search page, an autocomplete box or a product recommendation block asks: which products, in what order, with which filters and facets. Your theme or headless frontend calls it directly from the browser, or from your own server.

Base URL and regions

Everything is on one host:

https://mercury.plutocracy.io

The host is latency-routed: DNS sends each request to the nearest of four AWS regions (Sydney, N. Virginia, N. California and Frankfurt). The storefront routes (/search/* and /zone/*) are served from Redis in every region, so they're fast wherever your shoppers are. The reference gives the full URL of every route.

There is no separate sandbox host. To test, call the same API with a bypass token for a development store.

Authentication

Storefront routes need to know which store a request is for. They accept either of two credentials.

The Origin header. When your storefront's browser calls Mercury, it sends an Origin header (https://your-store.com). Mercury looks the origin up among the store's registered origins. This is the production path: there is nothing to configure in your code, and nothing secret ships to the browser. Origins of localhost and 127.0.0.1 are ignored, so local development needs a token.

A bypass token. For server-side calls, local development and scripts, add ?bypassToken=<token> to the query string. Tokens are issued per store from the Mercury admin. Treat a token like a password: it identifies the store to Mercury, so keep it out of public repositories.

curl "https://mercury.plutocracy.io/search/suggest/lin?bypassToken=$MERCURY_BYPASS_TOKEN"

When both are present the token is checked first. A request with neither, or with an unknown token, gets 401 in the standard error envelope.

The routes also read an X-BypassToken header, but the ?bypassToken= query parameter is the documented form: use it.

Your first request

Fetch the first page of search results from the browser on your storefront:

const res = await fetch('https://mercury.plutocracy.io/search/query/linen?take=24&skip=0');
if (!res.ok) throw new Error(`Mercury ${res.status}`);
const page = await res.json();
// page.products: the 24 products; page.facets: counts for the filters; page.suggested, page.redirect...

From a server or a terminal, add the token:

curl "https://mercury.plutocracy.io/search/query/linen%20shirt?take=20&bypassToken=$MERCURY_BYPASS_TOKEN"

All query values are strings on the wire, so take=24 is fine and so is take="24" in a URLSearchParams. Prices in rendered products are in major units (89.5, not 8950); see currencies and prices.