> ## Documentation Index
> Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Tracking

> How to retrieve tracking information for your orders

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

1. Your order is successfully placed with the retailer
2. The retailer ships the item and sends a shipping notification
3. We automatically extract tracking numbers from the notification
4. Tracking information appears in the order response

<Info>
  Tracking numbers are added to orders automatically. There is no separate endpoint to create or manage tracking numbers.
</Info>

## Tracking in Order Response

Tracking information is returned as part of the order response when you retrieve an order:

```json theme={null}
{
  "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](#tracking-status)). Always present. |
| `estimated_delivery_date` | string (date) \| null | Carrier-reported delivery estimate (see [Estimated Delivery Date](#estimated-delivery-date)).           |
| `checkpoints`             | array                 | Carrier scan events, most recent first (see [Checkpoint Timeline](#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                 |

<Info>
  The checkpoint timeline is embedded automatically on the single-order read ([`GET /orders/{order_id}`](/v2/api-reference/orders/get-order)). On the [List Orders](/v2/api-reference/orders/list-orders) endpoint it is omitted by default to keep payloads small — request it with `include=tracking_events`.
</Info>

## 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

```json theme={null}
{
  "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

<Warning>
  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](/v2/api-reference/introduction/webhooks) for push notifications.
</Warning>