Tracking

Get the same tracking information you see in your panel. Fetch it to show customers in your app or to update your order management system.

Tracking Numbers

Every order is assigned a unique tracking number when created:

4N YYYYMMDD NNNN

• 4N — prefix for regular orders. SH is used for orders that start from a blank label scanned by a driver in the field ("shell" orders) and keep that prefix for life.
• YYYYMMDD — the creation date.
• NNNN — a 4-digit code, randomly assigned. Don't infer volume or sequence from it.

For example, 4N202512310001 is an order created on 2025-12-31. Tracking numbers are always 14 characters: the two-letter prefix plus 12 digits. The tracking endpoint rejects any other shape with a 422.

Each package inside an order has its own tracking number, built from the order's: 4N202512310001-001, 4N202512310001-002, and so on.

Delivery states

The delivery_state field is the order's current position in the flow. These are the possible values:

See Orders for how an order moves between these states.

Timeline events

You get the same timeline you see when clicking an order in your panel — one entry per state change, oldest first. The first entry is always pending at the order's creation time.

A failed delivery attempt produces two entries at (almost) the same time: a failed entry carrying type: "failure" and failure_info with the details, and the resulting failed state change. Use the one with failure_info to tell your customer what happened.

Failure info

Reason codes: not_home, refused, wrong_address, inaccessible, business_closed, pending_stock_break, no_cargo_ready, no_cargo_to_ship, customer_unavailable, other.

Example Timeline

{
  "timeline": [
    { "state": "pending", "timestamp": "2025-02-03T10:00:00.000000Z" },
    { "state": "picked_up", "timestamp": "2025-02-03T14:30:00.000000Z" },
    { "state": "in_transit", "timestamp": "2025-02-03T18:00:00.000000Z" },
    { "state": "out_for_delivery", "timestamp": "2025-02-04T08:00:00.000000Z" },
    {
      "state": "failed",
      "timestamp": "2025-02-04T11:05:00.000000Z",
      "type": "failure",
      "failure_info": {
        "type": "Entrega fallida",
        "reason": "not_home",
        "notes": "Nobody answered the door"
      }
    },
    { "state": "failed", "timestamp": "2025-02-04T11:05:01.000000Z" },
    { "state": "out_for_delivery", "timestamp": "2025-02-05T08:30:00.000000Z" },
    { "state": "delivered", "timestamp": "2025-02-05T11:30:00.000000Z" }
  ]
}

Package progress

Orders with several packages can be delivered in parts. The tracking response gives you both the counters and the per-package detail:

Each entry in packages[] has:

Delivery attempts

delivery_attempts[] lists every visit to the recipient, in order, with its outcome and evidence — the same cards you see in the panel. Each attempt has:

Proofs

Three evidence blocks share the same core shape — location, notes, photos[] (url + preview_url) and created_at — and differ in when they're present:

recipient_role is one of merchant_staff, recipient, operator or other.

Location Object

{
  "location": {
    "latitude": -33.4489,
    "longitude": -70.6693
  }
}

Photos Array

{
  "photos": [
    {
      "url": "https://storage.example.com/proofs/abc123.jpg?signature=...",
      "preview_url": "https://storage.example.com/proofs/abc123-preview.jpg?signature=..."
    }
  ]
}

Photo links in the proof blocks are signed and valid for 60 minutes; the ones inside delivery_attempts[] last 2 hours. Fetch the tracking again to get fresh links — don't store them.

Full event history

The tracking timeline shows delivery states only. For the complete step-by-step history of an order — every change, who made it and when — use GET /orders/{reference}/events. It accepts either the tracking number or your own external_reference, so you can look an order up without storing our number first.

Get updates automatically

Instead of checking your panel or calling the API repeatedly, set up webhooks to get notified when orders move.

When to use what

See the Webhooks documentation for setup.