API / Fulfilment & delivery
When it is likely to arrive in a destination region, if ordered now. Regional windows with a stated confidence, the cutoff that produced them, and what changes if you order an hour later.
POST /v1/fulfillment/estimate
| Name | Type | Notes |
|---|---|---|
| ref | string | Product or offer reference. |
| destination | object | postal_code or region + country. Estimates are computed at metro/region granularity — see the scope note. |
| order_at | timestamp | Default now. Set it to test against a cutoff. |
| options | bool | Return every shipping tier rather than the default. |
POST /v1/fulfillment/estimate
{ "ref": "bestbuy:6505727",
"destination": { "postal_code": "10001", "country": "US" },
"order_at": "2026-09-08T16:40:00Z",
"options": true }
→ 200
{ "asked_at": "2026-09-08T16:40:00Z",
"options": [
{ "tier": "standard", "cost_minor": 0,
"window": { "earliest": "2026-09-10", "latest": "2026-09-12" },
"confidence": 0.86, "carrier": "ups",
"ships_from": { "region": "NJ", "distance_km": 34 } },
{ "tier": "express", "cost_minor": 1299,
"window": { "earliest": "2026-09-09", "latest": "2026-09-09" },
"confidence": 0.91, "carrier": "ups",
"cutoff": "2026-09-08T21:00:00Z",
"cutoff_in_minutes": 260,
"if_missed": { "earliest": "2026-09-10", "latest": "2026-09-10" } },
{ "tier": "pickup", "cost_minor": 0,
"window": { "earliest": "2026-09-08", "latest": "2026-09-08" },
"confidence": 0.95, "location": "Union Square, NYC",
"ready_in_minutes": 120 } ],
"granularity": "metro",
"region": "US-NY-NYC",
"notes": ["Regional estimate, not an address-level quote.",
"Estimates degrade around public holidays; confidence reflects that."] }SCOPE, STATED PLAINLY: these are *regional* estimates, not address-level promises. They are modelled per seller, per metro or region, per service tier and per season from observed behaviour on that lane. They are not a quote for one doorstep, and they do not account for the address-specific routing only a checkout can resolve. Address-level precision arrives with the checkout flow.
`cutoff_in_minutes` is the field an agent needs and almost no source exposes. A next-day promise that expires in twenty minutes is a materially different offer from one that expires in nine hours, and telling a user 'arrives tomorrow' without it produces a broken promise.
`if_missed` gives the consequence of missing the cutoff, so an agent can decide whether to hurry the user or quietly stop promising speed.
Confidence is real and it is a distribution, not a decoration. It falls around holidays, on long lanes and on sellers with thin observed history — which is precisely when an agent should widen what it promises rather than repeat a number it no longer trusts.