Order Tracking

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

Tracking numbers may not be available immediately after an order is placed. Check the order periodically to retrieve tracking information once items have shipped, or subscribe to the order.tracking_received and order.delivered webhook events for push notifications.

Getting Started

Search (Beta)

Orders

Bulk Orders

Managed Accounts

Returns

Product Data

Retailers

Agent

Usage

How Tracking Works

Tracking in Order Response

Tracking Number Fields

Tracking Status

Estimated Delivery Date

Checkpoint Timeline

Supported Carriers

Multiple Tracking Numbers

Tracking Links

When Tracking Is Available

​How Tracking Works

​Tracking in Order Response

​Tracking Number Fields

​Tracking Status

​Estimated Delivery Date

​Checkpoint Timeline

​Supported Carriers

​Multiple Tracking Numbers

​Tracking Links

​When Tracking Is Available

How Tracking Works

Tracking in Order Response

Tracking Number Fields

Tracking Status

Estimated Delivery Date

Checkpoint Timeline

Supported Carriers

Multiple Tracking Numbers

Tracking Links

When Tracking Is Available