Local availability — POST /v1/fulfillment/nearby

Local availability

What is physically in stock near a location right now, with distance and ready time. The answer to “I need this today”, which shipping cannot give.

POST /v1/fulfillment/nearby

Request

Name	Type	Notes
ref	string	Product reference.
near	object	postal_code or lat/lng.
radius_km	int	Default 40.

Request & response

POST /v1/fulfillment/nearby
{ "ref": "prd_8Fk2xQ", "near": { "postal_code": "10001" }, "radius_km": 25 }

→ 200
{ "locations": [
   { "seller": "bestbuy", "name": "Union Square", "distance_km": 2.1,
     "state": "in_stock", "quantity_band": "5+",
     "ready_in_minutes": 120, "price_minor": 19800 },
   { "seller": "target", "name": "Herald Square", "distance_km": 1.4,
     "state": "low_stock", "quantity_band": "1-2",
     "ready_in_minutes": 240, "price_minor": 29999 } ] }

Notes

Quantity is reported as a band, never as an exact count. Sellers expose exact counts inconsistently and change them constantly; a band is the honest resolution.

Local price frequently differs from online price at the same seller. Both are returned rather than assumed equal.