Shipments API
List and inspect shipments by carrier status or operational tracking state, handle access-blocked re-polls, query analytics/sync health, and export carrier status plus hold metadata.
List Shipments
/api/v1/shipments| Query | Values / purpose |
|---|---|
status | One or more comma-separated canonical carrier statuses |
trackingState | active or merchant-only held processing state |
startDate, endDate | ISO date/time range |
storeId | Merchant-owned store UUID |
carrier | Normalized carrier code |
search | Tracking/order search |
pollStatus | errors or stuck |
sortBy, sortOrder | Validated sort field and asc/desc |
page, limit | Pagination; limit is capped at 100 |
Shipment Detail and Re-poll
/api/v1/shipments/:id/api/v1/shipments/:id/repollDetail includes the carrier event timeline, trackingState, nullable trackingHoldReason, and merchant-safe poll diagnostics. Re-poll queues an immediate provider check and remains scoped to the authenticated merchant. A held shipment returns 402 SHIPMENT_ACCESS_BLOCKED with shipmentAccess, reason, and action details.
currentStatus or adds an event to the customer timeline.Analytics and Health
/api/v1/shipments/analytics/api/v1/shipments/volume-insights/api/v1/shipments/performance/api/v1/shipments/sync-healthvolume-insights returns the account-wide current calendar-month count, zero-filled completed-month average, current-month forecast and confidence, six-month history, and a 15%-headroom capacity recommendation. Analytics/performance accept date, store, carrier, and destination-country filters. Sync health reports active rows, normal polling, errors, stuck shipments, merchant-only billingHeld, and the latest successful poll.
Notification Log
/api/v1/shipments/notifications/log?page=1&limit=30Returns merchant notification sends with channel, recipient, trigger status, delivery status, attempts, errors, timestamps, and pagination metadata.
CSV Export
/api/v1/shipments/export-token/api/v1/shipments/export?_token=EXPORT_TOKEN- Call
POST /shipments/export-tokenwith a bearer access token. - Use the returned purpose-limited token within 60 seconds as
_tokenon the public export route. - Pass the same supported filters, including
trackingState, and sort options as the list view.
The CSV keeps Carrier Status, Tracking State, and Hold Reason in separate columns, is capped at 10,000 rows, neutralises spreadsheet formula prefixes, and is served with private/no-store and nosniff headers.
csv-export purpose claim.