37 endpoints across 9 groups. Every endpoint that takes a reference accepts whatever identifier you already hold — GTIN, UPC, EAN, ASIN, seller SKU, product link or plain language — and resolves it server-side.
Every request carries a bearer token and returns JSON. Responses include a request_id whether they succeed or fail — log it, because it is the only thing that identifies your exact call.
Read authentication for scopes and rotation, and errors for the codes and which are safe to retry.
curl https://api.commercecensus.com/v1/search?q=espresso \ -H "Authorization: Bearer $CENSUS_KEY" \ -H "Commerce Census-Version: 2026-09-01"
The index side. One query reaches every connected seller, in keywords or in plain language, and comes back as canonical products rather than a pile of listings.
| Endpoint | Path | Does |
|---|---|---|
| Search commerce | GET /v1/search | Keyword and structured search across every connected seller. |
| AI search | POST /v1/search/semantic | Intent in, products out. |
| Suggest | GET /v1/search/suggest | Typeahead over the canonical index. |
| Taxonomy | GET /v1/categories | One taxonomy across every seller, so a query does not have to know that one calls it “Audio” and another “Headphones & Earbuds”.. |
| Seller directory | GET /v1/sellers | Every seller in the index, with how it is accessed, refresh cadence, identity strength and coverage. |
The join. Callers hand over whatever identifier they happen to hold; resolution happens here, once, instead of in every codebase that touches the data.
| Endpoint | Path | Does |
|---|---|---|
| Resolve | POST /v1/resolve | GTIN, UPC, EAN, ASIN, seller SKU, product link or plain language into one canonical product and every listing that carries it.. |
| Bulk match | POST /v1/match | Send up to 10,000 of your own rows and get canonical ids back, each with a method and a confidence — including the ones we refuse to guess at.. |
| Product | GET /v1/products/{id} | The canonical record: identity, attributes, taxonomy, media, and every variant.. |
| Media & photos | GET /v1/products/{id}/media | Every image we hold for a product and its variants, with pre-computed renditions, true dimensions and the role each one plays.. |
| Attributes | GET /v1/products/{id}/attributes | Structured, category-aware attributes normalised across sellers — with the source and confidence of each value, because a parsed number is not a declared one.. |
| Facets | GET /v1/facets | The filterable axes for a category and their real value distributions — how you build a filter UI that matches what actually exists rather than what you guessed.. |
| Checkout — coming soon | POST /v1/checkout | COMING SOON. |
| Offers | GET /v1/products/{id}/offers | Every live offer for a product, with seller identity, landed cost, condition and the provenance of each value.. |
The part a single lookup cannot produce. A figure is a reading; a percentile against a product's own history is a judgment, and that is what a buyer — human or not — actually needs.
| Endpoint | Path | Does |
|---|---|---|
| Compare | POST /v1/compare | One product across every seller that carries it, ranked by landed cost, with the spread. |
| Price context | GET /v1/products/{id}/context | Is this actually a good price? Percentile against the product's own history at that seller, time-weighted, with low, median and high.. |
| History | GET /v1/products/{id}/history | The observation series. |
| Forecast | GET /v1/products/{id}/forecast | Whether to buy now or wait, from the product's own seasonality and discount rhythm — with the confidence interval shown rather than hidden.. |
| Availability | GET /v1/products/{id}/availability | Stock state across sellers, with stockout frequency. |
An index is stateless; a shopper is not. Memory gives an agent somewhere durable to keep what it learned about a person — budgets, brands they refuse, a watch they set in March — so the next conversation does not restart from nothing.
| Endpoint | Path | Does |
|---|---|---|
| Write memory | POST /v1/memory | Store a durable fact for a namespace you control. |
| Recall | POST /v1/memory/query | Semantic recall scoped to one namespace. |
| Forget | DELETE /v1/memory/{id} | Deletion is a first-class operation, not a support ticket. |
Polling is a tax on both sides. A watch is a standing subscription with a signed callback, and the event log is replayable so a missed delivery is self-serve at 2am rather than a support ticket.
| Endpoint | Path | Does |
|---|---|---|
| Watches | POST /v1/watches | A standing condition on a product, a seller, a brand or a whole category.. |
| Events | GET /v1/events | Six event types, signed on delivery and replayable by cursor. |
| Live stream | GET /v1/stream | Server-sent events for anything that cannot wait for a webhook round trip.. |
Four surfaces over one record shape. Same truth, different contract — nothing in between to disagree with itself.
| Endpoint | Path | Does |
|---|---|---|
| MCP server | MCP @commercecensus/mcp | Six tools, not thirty endpoints. |
| Agent feeds | FEED /v1/feed/{protocol} | Your catalogue in the shape agentic checkout already parses, so it is legible to conversational commerce surfaces without a bespoke integration.. |
| Bulk export | GET /v1/exports | The whole index, or your slice of it, as newline-delimited JSON or Parquet. |
The hardest question in commerce is not what something costs, it is whether two things are the same thing. An agent that gets this wrong recommends a 2-pack against a 6-pack, or last year's model against this year's, and the price comparison it built on top is worse than useless.
| Endpoint | Path | Does |
|---|---|---|
| Equivalence | POST /v1/equivalence | Are these the same product? Returns one of five relations with the specific attributes that differ and a confidence — because 'similar' is not an answer a machine can act on.. |
| Substitutes | POST /v1/substitutes | Find what else does this job, with every meaningful difference enumerated and priced. |
| Decide | POST /v1/decide | Intent and constraints in, a ranked recommendation out — with the reasoning, the runner-up, and what would change the answer. |
| Total cost | GET /v1/products/{id}/total-cost | What it costs to own, not to buy. |
Delivery is not a property of a product. It is a function of the product, the seller, the destination, the inventory location, the carrier and the moment you ask — and it routinely decides a purchase that price alone would have decided differently.
| Endpoint | Path | Does |
|---|---|---|
| Delivery estimate | POST /v1/fulfillment/estimate | When it is likely to arrive in a destination region, if ordered now. |
| Local availability | POST /v1/fulfillment/nearby | What is physically in stock near a location right now, with distance and ready time. |
| Returns & warranty | GET /v1/offers/{id}/returns | The terms attached to an offer: return window, who pays return shipping, restocking fees, warranty length and who honours it.. |
Price and delivery describe the offer. These describe whether it will go wrong — which is what separates a recommendation an agent can stand behind from a cheap listing it found.
| Endpoint | Path | Does |
|---|---|---|
| Seller trust | GET /v1/sellers/{id}/trust | Observed reliability rather than a star rating: fulfilment record, cancellation rate, how long they have existed, and whether they are authorised for the brand.. |
| Offer risk | GET /v1/offers/{id}/risk | Flags on an individual offer: price far below the product's own distribution, a seller new to the listing, condition ambiguity, region mismatch.. |
| Review signal | GET /v1/products/{id}/reviews | Aggregate sentiment across sellers, decomposed into the attributes people actually complain about — not a single star average that hides everything.. |