Search, collections and products

The routes a collection page, a search page, an autocomplete box and a product block call, and how paging, facets, redirects and suggestions behave.

These routes are served from Redis in every region, and all of them take the same credentials.

If you'd rather not build the collection grid yourself, the Collection Kit renders it from this same route, and lets you replace any part of it.

#Collections

curl "https://mercury.plutocracy.io/search/collection/summer?take=24&skip=0&bypassToken=$MERCURY_BYPASS_TOKEN"

The response is the collection itself (title, handle, body_html, metafields, sort_order, any merchandising campaign) with the page of products and the facets for the filter sidebar. Products are rendered: prices are in major units, and prices is narrowed to ?currency= when you send one.

• An unknown handle answers 404 Collection not found.
• An empty handle answers 400 No handle specified.
• Products hidden from collections (tagged __HIDDENCOLLECTION or __HIDDEN in Shopify) never appear.
• With no sort, the collection's own Shopify sort order applies. See sorting collections.

#Search

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

Encode the term as a path segment. The response carries:

• products and their facets;
• search, the term that was executed;
• query, the parsed filters;
• suggested, alternative terms from the store's suggestion dictionary;
• redirect.

Notes:

• Redirects. A merchant can send a search term to a page, such as "returns" to the returns policy. When the term has a redirect, redirect is the URL to send the shopper to; otherwise it is null. The lookup always runs: the red parameter is accepted but ignored.
• Suggestions. suggested is always computed (fuzzy, from the store's dictionary). It is [] when the dictionary lookup fails. The sug parameter is ignored too.
• Empty terms. Don't call the route without a term. A term of the literal string undefined answers 400 No term specified, which catches a common template bug.
• Hidden products. Products hidden from search (tagged __HIDDENSEARCH or __HIDDEN in Shopify) never appear.
• Order. With no sort, results come back in relevance order.

#Autocomplete

GET /search/suggest/{term} returns suggestion strings from the store's dictionary, fuzzy-matched. It is cheap, but debounce keystrokes by 150–250 ms rather than calling on every one.

#Products by handle

GET /search/product/{handles} takes up to 20 comma-separated handles and returns rendered products, in the order you asked:

• Prices are in major units.
• prices is narrowed to ?currency= when you send one.
• A handle that doesn't match a product comes back as null in its slot, so check before rendering.

curl "https://mercury.plutocracy.io/search/product/linen-shirt,cotton-tee?currency=AUD&bypassToken=$MERCURY_BYPASS_TOKEN"

#Paging

Collections and search page the same way:

Prefer take and skip. A negative pageNumber answers 400, but page=0 is ignored and a negative page produces a negative offset, so validate page numbers before sending them. The counts are in facets (see filters and sorting).

#Including the grid config

Send grid_config=1 to get the store's grid configuration in the same response: the facet, colour, size and image mappings, and the grid layout. A widget then needs one request instead of two. The check is for presence, so grid_config=false also includes it. Leave the parameter out to exclude it.

#Analytics

Mercury counts searches and collection views for the merchant's reports. Send tracking=none from previews, bots you control and monitoring, so they don't skew the numbers. userId lets you attach a stable anonymous id of your own.

#Errors you will see

• 401 without a credential.
• 400 for a bad page number, an empty collection handle or the undefined search term.
• 404 for an unknown collection.
• 406 when the search engine rejects the query, usually because of a malformed filter.

All of them use the error envelope.