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

> Retrieve carrier tracking numbers and delivery status for your Zinc 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)). |
| `delivery_proof_url` | string \| null | URL of the carrier's proof-of-delivery photo, when one was captured. Usually appears once the shipment is `delivered`; `null` when there's none. |
| `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 |
| `available_for_pickup` | Waiting at a carrier facility for the recipient to collect |
| `delivered` | Delivered to the address |
| `undeliverable` | The carrier couldn't deliver it: undeliverable, on hold, or returning to sender |

`available_for_pickup` and `undeliverable` aren't necessarily final. A package waiting for pickup can still go back out for delivery or be returned, and a package marked undeliverable can still pick up scans on its way back to the sender. Each package moving into `available_for_pickup` also fires an [`order.available_for_pickup`](/docs/v2/api-reference/introduction/webhooks#order-events) webhook.

## 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 (one of the [Tracking Status](#tracking-status) values) |
| `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}`](/docs/v2/api-reference/orders/get-order)). On the [List Orders](/docs/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](/docs/v2/api-reference/introduction/webhooks) for push notifications.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.