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

/config

Header parameters

Originstringrequired

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

X-BypassTokenstring

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

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://mercury.plutocracy.io/config' \
  --header 'Origin: text'

200

200

No body

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

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

/suggest/{term}

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-BypassTokenstring

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

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://mercury.plutocracy.io/suggest/{term}' \
  --header 'Origin: text'

200

200

No body

Suggested autocomplete terms from the autocomplete dictionary

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

/search/{term}

Path parameters

termstringrequired

The term to search the Search Index for

Query parameters

sugboolean

Allow the search to return similar search terms

redboolean

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

pageNumbernumber

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

querystring

Additional filter objects - Stringified

skipnumber

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

takenumber

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-BypassTokenstring

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://mercury.plutocracy.io/search/{term}' \
  --header 'Origin: text'

200

200

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

A complete Rendered Search

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

/collection/{handle}

Query parameters

pageNumbernumber

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

querystring

Additional filter objects - Stringified

skipnumber

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

takenumber

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-BypassTokenstring

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://mercury.plutocracy.io/collection/{handle}' \
  --header 'Origin: text'

200

200

{
  "id": 1,
  "title": "text",
  "handle": "text",
  "body_html": "text",
  "metafields": {},
  "sort_order": "text",
  "updated_at": "2025-02-22T08:39:43.950Z",
  "disjunctive": true,
  "published_at": "2025-02-22T08:39:43.950Z",
  "collection_type": "text",
  "published_scope": "text",
  "template_suffix": "text",
  "admin_graphql_api_id": "text",
  "config": {},
  "facets": {
    "count": 1,
    "vendors": [
      {
        "vendor": "text",
        "count": 1
      }
    ],
    "types": [
      {
        "type": "text",
        "count": 1
      }
    ],
    "tags": [
      {
        "value": "text",
        "count": 1
      }
    ]
  },
  "rules": [
    {
      "column": "text",
      "relation": "text",
      "condition": "text"
    }
  ]
}

A complete Rendered Collection

Get Products

get

/search/product/{handles}

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-BypassTokenstring

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://mercury.plutocracy.io/search/product/{handles}' \
  --header 'Origin: text'

200

200

[
  {
    "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,
    "prices": {},
    "created_date": "2025-02-22T08:39:43.950Z",
    "image": "text",
    "related": "text",
    "meta": {
      "reviews": {},
      "badges": [
        {
          "content": "text",
          "background": "text",
          "colour": "text",
          "positiony": "text",
          "positionx": "text",
          "classes": "text",
          "type": "text"
        }
      ]
    },
    "variants": [
      "text"
    ],
    "tags": [
      "text"
    ],
    "images": [
      "text"
    ]
  }
]

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