Get Coverage History
GET/api/send-planner/coverage/history
Daily playback frames of where a product (or a whole network) was stocked and its estimated 2-day reach. The first frame is complete; later frames carry only the keys that changed. Also returns FC-to-FC transfers, inbound shipments (ship to receipt), days with no data and units that could not be placed on the map.
send-plans:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
The range is at most 548 days (18 months). Without from/to it covers the last 90 days up to today. Dates are YYYY-MM-DD.
All figures are estimates: the share of a product's buyers (by order postal area) within estimated 2-day ground reach (great-circle distance ≤ the radius) of a fulfillment center or warehouse holding sellable stock. They are not the marketplace's delivery promise; every response carries as_of and the radius.
Authentication: a Personal Access Token in the Authorization header with the send-plans:read scope. The token's user also needs permission to view the send planner.
Response fields: as_of (the last frame's date), radius_miles, unit, country, nodes[] (located nodes: code, label, city, admin1, lat, lng, type, plus warehouse_id for your own warehouses), frames[] ({date, coverage_pct, nodes: {code: units}, admin1: {code: covered share}}; later frames only the changed keys), transfers[] ({date, from, to, units}), inbound[] (only when product_id is given: every shipment on its way at some point of the range, received ones included: {shipment_id, origin, to, shipped, received, eta, units, shipment_record_id, shipment_record_type, shipment_route, network}; received is the day of the shipment's last receipt once it is fully received, null while it is on its way; units are the shipped quantity; shipment_record_id is the inbound shipment's ID in SKU.io and shipment_route the path of its detail page), missing_days, history_starts, network_set (whole-network requests only: {products, weighting, send_plan_id, plan_as_of}), unplaced {units, codes} and unsupported_reason (set, with every list empty, for a network that is not measured).
Whole network (no product_id): coverage_pct is the velocity-weighted mean of per-product reach over the products the send plan measured on that network (send_plan_id, default the latest working plan), weighted by the plan's velocity, the same definition as the plan's own figure. Node units are summed over those products only. The frame on or after the plan's as-of day uses each product's "before" from the plan, so the last frame equals the plan's before. Without a plan, every product stocked at the network is used, weighted by units sold.
Returns 422 when the range is longer than 548 days, the end is before the start, the network is unknown or has no regional coverage, or the destination or product does not exist.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.