Known v1 quirks

What the v1 wire actually sends where it differs from what you'd expect. v1 keeps these for compatibility; v2 fixes them.

Mercury's v1 storefront API has grown with its storefronts, and some responses carry history. The contracts in the reference describe the wire as it is, quirks included, and existing storefronts depend on that, so v1 won't change shape to fix them. v2 is where they go away. Code defensively against everything below.

#Data shapes

These come from comparing the contracts with sampled production responses (the storefront contract check, !187, and the v2 sizing work):

• Ids are strings, numbers, or both. Products indexed from Shopify's GraphQL API carry GIDs (gid://shopify/Product/1) or numeric strings; older ones carry numbers; a list can mix them. Compare ids as strings: String(a) === String(b).
• on_sale is a boolean or 0/1. Test truthiness, not === true.
• image (and images) can be absent on products without images. Always have a placeholder.
• Presentment amounts are strings. prices[CODE].price and variants[].price are decimal strings, sometimes numbers. Parse with Number().
• Prices of zero are absent. min_price is left out rather than 0; see currencies and prices.
• A missing product is null in its slot of a /search/product/{handles} response, not removed. (The Collection Kit contract's products route sends {} instead.)
• query in a response echoes your input, parsed, rather than describing what was applied.

#Parameters

• grid_config=false includes the grid config. The check is "present and non-empty"; leave the parameter out to exclude it.
• red and sug are ignored on search: redirects and suggestions are always computed.
• page=0 is ignored and a negative page gives a negative offset; only pageNumber is validated. Use take and skip.
• sort takes Mercury's names only; a Shopify name gives relevance order on search and manual order on a collection. See sort names.

#Routes

• The zone POST answers 201, and some zone answers have an empty body. See zones.
• A search term of undefined answers 400, which catches templates that interpolate a missing value.

Each reference page lists the quirks its contract records, under Known quirks.