Home / Platform
One record shape, four contracts.
The same observation reaches a dashboard, a repricing engine, a shopping agent and a checkout surface. Each wants a different shape; none should get a different truth.
Model
Store observations, not prices.
A price is a mutable current-state field. An observation is an immutable fact: this source reported this value at this instant. Store observations and current price becomes a view; store prices and you have thrown away the asset you were trying to build.
Each observation carries when the source said it and when we learned it — those differ, and the gap matters. Deduplication is on content, so an unchanged reading still counts as a poll but writes nothing. Done properly the series is the change log.
observation( product_id, seller_id, offer_id, observed_at, // when the source said it ingested_at, // when we learned it price_minor, currency, shipping_minor, availability, offer_type, seller, source_channel, // direct_api | merchant_feed | verified_agent | listing_view confidence, // weight, not a boolean raw_hash // dedupe identical consecutive reads )
Provenance
Every value carries its origin.
Surface area
What the API covers.
5 endpoints
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.
8 endpoints
The join. Callers hand over whatever identifier they happen to hold; resolution happens here, once, instead of in every codebase that touches the data.
5 endpoints
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.
3 endpoints
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.
3 endpoints
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.
3 endpoints
Four surfaces over one record shape. Same truth, different contract — nothing in between to disagree with itself.
4 endpoints
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.
3 endpoints
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.
3 endpoints
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.