Endpoints

Fetch a stores Public Config

Mercury exposes it's grid configuration object as a store metafield

store.metafields.MERCURY.grid
store.metafields.MERCURY.sizemapping
store.metafields.MERCURY.colourmapping
store.metafields.MERCURY.imagemapping

But you can also fetch it directly from the API

get

Header parameters

OriginstringRequired

Whitelisted origins will return store data for a given URL - used for Production Traffic

X-BypassTokenstringOptional

A Mercury Provided Bypass Token, will provide scoped access to a stores data - used for Local Development

Responses

200

Returns the current Grid Config, Facet Map, Colour Map, Size Map etc

No content

get

/config

HTTPcURLJavaScriptPython

GET /config HTTP/1.1
Host: mercury.plutocracy.io
Origin: text
Accept: */*

200

Returns the current Grid Config, Facet Map, Colour Map, Size Map etc

No content

Search Endpoints

Mercury's core experience is our Search & Merch Engine. It consists of some key endpoints, which handle the heavy lifting for you to create seamless Search & Collection experiences using our embeddable experience or your own custom experience.

Suggest

Suggest returns a list of similar / popular search terms related to your query

Available on Mercury Pro/Enterprise Plans

get

Path parameters

termstringRequired

The term to search the Autocomplete Dictionary for

Header parameters

OriginstringRequired

Whitelisted origins will return store data for a given URL - used for Production Traffic

X-BypassTokenstringOptional

A Mercury Provided Bypass Token, will provide scoped access to a stores data - used for Local Development

Responses

200

Suggested autocomplete terms from the autocomplete dictionary

No content

get

/suggest/{term}

HTTPcURLJavaScriptPython

GET /suggest/{term} HTTP/1.1
Host: mercury.plutocracy.io
Origin: text
Accept: */*

200

Suggested autocomplete terms from the autocomplete dictionary

No content

Search

Search returns a page of search results for a given search term

The engine will handle

• Synonym Matching

• Search Modifiers

• Saved Searches

• Redirects

Learn more here

get

Path parameters

termstringRequired

The term to search the Search Index for

Query parameters

sugbooleanOptional

Allow the search to return similar search terms

redbooleanOptional

Allow the search to return redirect URLs for the given search term

pageNumbernumberOptional

A page number to return the results from, pages are calculated from the take param (default 20)

querystringOptional

Additional filter objects - Stringified

skipnumberOptional

The amount of results to skip, should be a multiple of the "Take"

takenumberOptional

The amount of results to return, (max 50, default 20)

Header parameters

OriginstringRequired

Whitelisted origins will return store data for a given URL - used for Production Traffic

X-BypassTokenstringOptional

A Mercury Provided Bypass Token, will provide scoped access to a stores data - used for Local Development

Responses

200

A complete Rendered Search

application/json

get

/search/{term}

HTTPcURLJavaScriptPython

GET /search/{term} HTTP/1.1
Host: mercury.plutocracy.io
Origin: text
Accept: */*

200

A complete Rendered Search

{
  "search": "text",
  "facets": {
    "vendors": [
      {
        "vendor": "text",
        "count": 1
      }
    ],
    "types": [
      {
        "type": "text",
        "count": 1
      }
    ],
    "tags": [
      {
        "value": "text",
        "count": 1
      }
    ],
    "count": 1
  },
  "products": [
    []
  ],
  "query": [
    "text"
  ],
  "redirect": "text",
  "suggested": [
    "text"
  ]
}

Collection Endpoints

Collection returns a page of collection results for a given collection query term

The engine will handle

• Sorting based on advanced rules

• Collection merchandising content

• Inline merchandising content

When constructing the grid, you will have to merge the merchandising content and the product content to match the configuration of the store's config to allow the mercury admin preview to match the end users collection experience

Learn more here

get

Query parameters

pageNumbernumberOptional

A page number to return the results from, pages are calculated from the take param (default 20)

querystringOptional

Additional filter objects - Stringified

skipnumberOptional

The amount of results to skip, should be a multiple of the "Take"

takenumberOptional

The amount of results to return, (max 50, default 20)

Header parameters

OriginstringRequired

Whitelisted origins will return store data for a given URL - used for Production Traffic

X-BypassTokenstringOptional

A Mercury Provided Bypass Token, will provide scoped access to a stores data - used for Local Development

Responses

200

A complete Rendered Collection

application/json

get

/collection/{handle}

HTTPcURLJavaScriptPython

GET /collection/{handle} HTTP/1.1
Host: mercury.plutocracy.io
Origin: text
Accept: */*

200

A complete Rendered Collection

{
  "id": 1,
  "rules": [
    {
      "column": "text",
      "relation": "text",
      "condition": "text"
    }
  ],
  "title": "text",
  "handle": "text",
  "body_html": "text",
  "metafields": {},
  "sort_order": "text",
  "updated_at": "2026-02-07T05:13:55.997Z",
  "disjunctive": true,
  "published_at": "2026-02-07T05:13:55.997Z",
  "collection_type": "text",
  "published_scope": "text",
  "template_suffix": "text",
  "admin_graphql_api_id": "text",
  "config": {},
  "facets": {
    "vendors": [
      {
        "vendor": "text",
        "count": 1
      }
    ],
    "types": [
      {
        "type": "text",
        "count": 1
      }
    ],
    "tags": [
      {
        "value": "text",
        "count": 1
      }
    ],
    "count": 1
  }
}

Get Products

get

Path parameters

handlesstringRequired

A comma separated list of product handles

Header parameters

OriginstringRequired

Whitelisted origins will return store data for a given URL - used for Production Traffic

X-BypassTokenstringOptional

A Mercury Provided Bypass Token, will provide scoped access to a stores data - used for Local Development

Responses

200

Up to 20 product objects, if only one handle is specified it will return an object

application/json

get

/search/product/{handles}

HTTPcURLJavaScriptPython

GET /search/product/{handles} HTTP/1.1
Host: mercury.plutocracy.io
Origin: text
Accept: */*

200

Up to 20 product objects, if only one handle is specified it will return an object

[
  {
    "id": "text",
    "title": "text",
    "implode": 1,
    "handle": "text",
    "min_price": 1,
    "compare_at_min_price": 1,
    "vendor": "text",
    "type": "text",
    "on_sale": true,
    "total_stock": 1,
    "variants": [
      "text"
    ],
    "prices": {},
    "created_date": "2026-02-07T05:13:55.997Z",
    "tags": [
      "text"
    ],
    "image": "text",
    "images": [
      "text"
    ],
    "related": "text",
    "meta": {
      "reviews": {},
      "badges": [
        {
          "content": "text",
          "background": "text",
          "colour": "text",
          "positiony": "text",
          "positionx": "text",
          "classes": "text",
          "type": "text"
        }
      ]
    }
  }
]