Skip to main content

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.

Required scope: send-plans:read

Grant 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​

OK

Response Headers
    Content-Type