Once an order has been placed with a retailer, tracking information becomes available as shipments are dispatched. Tracking numbers are automatically extracted from retailer shipping notifications and associated with your order.
How Tracking Works
- Your order is successfully placed with the retailer
- The retailer ships the item and sends a shipping notification
- We automatically extract tracking numbers from the notification
- Tracking information appears in the order response
Tracking numbers are added to orders automatically. There is no separate endpoint to create or manage tracking numbers.
Tracking in Order Response
Tracking information is returned as part of the order response when you retrieve an order:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "order_placed",
"tracking_numbers": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"carrier": "ups",
"tracking_number": "1Z999AA10123456784",
"status": "in_transit",
"estimated_delivery_date": "2026-01-18",
"checkpoints": [
{
"checkpoint_time": "2026-01-16T08:12:00Z",
"status": "in_transit",
"message": "Departed shipping facility",
"city": "Louisville",
"state": "KY",
"country": "US",
"zip": "40209",
"location": null
},
{
"checkpoint_time": "2026-01-15T18:40:00Z",
"status": "pending",
"message": "Shipping label created",
"city": null,
"state": null,
"country": "US",
"zip": null,
"location": null
}
],
"created_at": "2026-01-15T14:30:00Z"
}
],
...
}
Tracking Number Fields
| Field | Type | Description |
|---|
id | string (UUID) | Unique identifier for the tracking record |
carrier | string | Shipping carrier (see supported carriers below) |
tracking_number | string | The carrier’s tracking number |
status | string | Authoritative carrier-derived shipment state (see Tracking Status). Always present. |
estimated_delivery_date | string (date) | null | Carrier-reported delivery estimate (see Estimated Delivery Date). |
checkpoints | array | Carrier scan events, most recent first (see Checkpoint Timeline). |
created_at | string (ISO 8601) | When the tracking number was extracted |
Tracking Status
The status field is the carrier-derived state of the shipment and is always present on each tracking number:
status value | Description |
|---|
pending | Label created; not yet scanned in transit |
in_transit | Moving through the carrier network |
delivered | Delivered to the address |
Estimated Delivery Date
estimated_delivery_date is the carrier’s current delivery estimate for the shipment, as a calendar date in the destination’s local time zone (e.g. "2026-01-18"). It is refreshed on every carrier poll, so the value can shift as the carrier revises its estimate. It is null when the carrier hasn’t reported an estimate — typically until the first in-transit scan — so always handle the null case.
Checkpoint Timeline
checkpoints is the per-scan history of a tracking number, most recent first. Each checkpoint is a single carrier-reported scan event:
| Field | Type | Description |
|---|
checkpoint_time | string (ISO 8601) | When the carrier recorded this scan |
status | string | Shipment state at this checkpoint (pending, in_transit, delivered) |
message | string | Carrier-provided description of the scan |
city | string | null | Scan city, when available |
state | string | null | Scan state/region, when available |
country | string | null | Scan country, when available |
zip | string | null | Scan postal code, when available |
location | string | null | Free-form location string when city/state are absent |
The checkpoint timeline is embedded automatically on the single-order read (GET /orders/{order_id}). On the List Orders endpoint it is omitted by default to keep payloads small — request it with include=tracking_events. Supported Carriers
The following carriers are automatically detected:
| Carrier | carrier value | Example Format |
|---|
| UPS | ups | 1Z999AA10123456784 |
| FedEx | fedex | 123456789012 |
| USPS | usps | 9400111899223033005001 |
| Amazon Logistics | amazon | TBA123456789000 |
| DHL | dhl | 1234567890 |
Multiple Tracking Numbers
An order may have multiple tracking numbers if:
- Items ship separately from the retailer
- Multiple products in the order ship from different fulfillment centers
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "order_placed",
"tracking_numbers": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"carrier": "ups",
"tracking_number": "1Z999AA10123456784",
"created_at": "2026-01-15T14:30:00Z"
},
{
"id": "8d0f7780-8536-51ef-055c-f18fd2g01bf8",
"carrier": "amazon",
"tracking_number": "TBA123456789000",
"created_at": "2026-01-16T09:15:00Z"
}
]
}
Tracking Links
You can construct tracking URLs for each carrier:
| Carrier | Tracking URL |
|---|
| UPS | https://www.ups.com/track?tracknum={tracking_number} |
| FedEx | https://www.fedex.com/fedextrack/?trknbr={tracking_number} |
| USPS | https://tools.usps.com/go/TrackConfirmAction?tLabels={tracking_number} |
| Amazon | https://www.amazon.com/progress-tracker/package/?trackingId={tracking_number} |
| DHL | https://www.dhl.com/us-en/home/tracking.html?tracking-id={tracking_number} |
When Tracking Is Available
Tracking numbers appear after the order status changes to order_placed and the retailer has shipped the item. The timing depends on:
- Retailer processing time
- Shipping method selected
- Product availability
