Response Schema

Five types cover every marketplace operation. A field means the same thing wherever it appears, and every concept has exactly one name — a delivery is the same shape on a search card, a product, an offer and a shipping quote.

Optional fields are genuinely optional: absent means the marketplace did not say, never a default. An absent price is a listing with no current offer, not a free one. An absent delivery.cost is shipping that has not been priced yet, not free shipping — that is delivery.free: true, a different claim.

Which optional fields a given marketplace actually fills varies a lot; each marketplace page has the measured rates.

SearchResult

{
  "marketplace": "amazon",
  "query": "running shoes",
  "page": { "index": 1, "size": 48, "total": 1200 },
  "items": [ /* SearchItem */ ],
  "cursor": "…"
}

Facet

The site's own filter rail, for this query. Absent means no rail was returned; [] means there is no rail for this query.

value is what you send back in the facets request parameter. It is the human-readable label rather than an internal id.

Where maps_to is present, prefer that typed parameter: it means the same thing on every marketplace.

SearchItem and Product

Both extend one item shape, so a field means the same in a result card and on a product page. Product adds what only a detail view has.

Shared by Both

Money is {currency, amount} with amount in decimal major units.

ext is a last resort: a fact goes into a shared typed field whenever one means the same thing, and only a fact no other marketplace has rides in ext, under that marketplace's own name. Items, variants, sellers, offers, reviews, review pages and category nodes can carry one.

DeliveryOption

One shape for every delivery — delivery, each of shippingOptions, an offer's delivery, and each option of a ShippingQuote.

An absent cost is unstated, not free; free is free: true. available: false is an answer, never a zero cost. delivery is always the option that applies to every buyer when the marketplace shows one — a member-only free (Prime) is in shippingOptions with its membership, never presented as everyone's.

Seller

rating.grouped: true means the aggregate covers the whole variation family rather than the one variant asked for. Its absence means not known to be grouped, which is weaker than "known to be per-variant".

SearchItem Only

Product Only

Variants, and the One Thing to Check

Two variation models exist in the wild, and one field tells them apart:

• variant.productId present — the combination is its own fetchable product. Pass that id back to product. Amazon works this way.
• variant.productId absent — the combination only exists inside this product; you already have everything. Shopify, Walmart and AliExpress work this way.

You never need to know which marketplace you are talking to. Check the field.

Offer

A competing seller, where the marketplace enumerates them: {seller?, price, listPrice?, condition?, conditionNote?, fulfilledBy?, inStock?, status?, delivery?}. delivery is a DeliveryOption, because a cheaper offer that ships later is a different offer.

ReviewPage

{
  "marketplace": "walmart",
  "productId": "996425081",
  "summary": { "average": 4.6, "count": 1204, "distribution": { "5": 78 } },
  "page": { "index": 1, "size": 10, "total": 990 },
  "reviews": [ /* Review */ ],
  "grouped": true
}

A Product with No Reviews

It answers 200 with an explicit zero, so you can show "0 reviews" with confidence:

{ "marketplace": "shopify", "productId": "shop.com/handle", "page": { "index": 1, "size": 0, "total": 0 }, "reviews": [] }

page.total: 0 is only ever sent when the product genuinely has none. If there is evidence that the product has reviews that are not available — a count or an average is reported, or the product page shows them — you get an error instead, never a zero. So an empty reviews array tells you one of two things, and page.total says which:

There is no summary on a zero answer: there is no average to report.

grouped is a required disclosure rather than a detail. A merchant can answer one colour's page with the family's 9,000 reviews and nothing in the reviews themselves says so — computing "this product's rating" from a grouped page gives you the family's.

review.incentivized: true marks a review written in exchange for something (a free product, a sample, a reward), as the marketplace labels it; absent means not marked, never "known to be unpaid". review.reply is the merchant's public response: {body, date?, author?}.

review.variant names the sibling a review was written for, when the marketplace says. Inside a grouped page an empty variant means the marketplace would not say, never "this one is for the product you asked for".

page.total and summary.count count different things: a product can report 7,654 ratings while its review list holds 990 written reviews, so the count stays true to the product and the total to the list. Neither promises that every review is reachable: marketplaces cap how far a list pages, and the list ends when the cursor does.

CategoryList

What categories returns: one flat list, every node naming its parent. Flat rather than nested because the common request is "the whole taxonomy", and nesting makes that both larger on the wire and harder to page. Rebuilding the tree is a groupBy on parentId.

{
  "marketplace": "aliexpress",
  "path": [ { "id": "200000345", "name": "Women's Clothing" } ],
  "categories": [
    { "id": "349", "name": "Skirts", "parentId": "200000345" },
    { "id": "201531101", "name": "Matching Sets", "parentId": "200000345" }
  ]
}

CategoryNode

Unlike most of this schema, id and name are both required. A category listing exists to be acted on: an entry without an id is unusable and one without a name unreadable.

browsable — the One Field Worth Reading Carefully

Absent means yes, which is the normal case. false marks a level that is real and navigable but has no listing page behind it.

Every marketplace here has such levels, and they are not an edge case:

When you meet one, descend one more level with categories and the ids there will browse.

Pass browsableOnly=true to categories to get only the ids browse accepts — see the marketplaces overview for what it costs and when it 400s.

You Do Not Have to Trust the Flag

browsable is populated only where it has been established, so a level that cannot be browsed can still reach you with the field absent — that is, optimistically. On Walmart this is unavoidable: Electronics (3944) and Toys (4171) are both departments with children, and one lists products while the other does not, with nothing in the taxonomy to tell them apart.

So browse tells you outright. Asking it for a category that has no listing page returns

{ "success": false, "error": { "code": "CATEGORY_NOT_BROWSABLE", "message": "Walmart category 4171 is a navigation hub…" } }

rather than an empty list — because an empty list is also what a sold-out category returns, and you would have no way to tell "descend to the children" from "nothing for sale here". Treat the code as the instruction to call categories with that same id and browse one of its children. It is a 400, not a failure of the request: retrying will not change the answer.

ShippingQuote

What shipping returns: every way one item ships to one region, cheapest first.

{
  "marketplace": "aliexpress",
  "productId": "1005012143419303",
  "skuId": "12000057632572864",
  "region": "US",
  "quantity": 1,
  "available": true,
  "options": [
    { "carrier": "YunExpress Standard Shipping", "cost": { "currency": "USD", "amount": 3.13 },
      "free": false, "minDays": 7, "maxDays": 15, "guaranteedDays": 60,
      "estimate": "Oct. 30 - Nov. 07", "tracking": true, "shipsFrom": "CN" }
  ]
}

options are DeliveryOptions. available: false with no options means the marketplace does not ship there — an answer, not an error.

Errors

{ "success": false, "error": { "code": "INVALID_PARAMS", "message": "…" } }

A 501 is never a 404 on purpose: "these reviews are not available" must not read as "this product has no reviews".