Core concepts

Delivery lifecycle

A delivery moves through a fixed set of states, each written to an event timeline as it happens. Your integration should read the status and show the timeline — not infer progress from elapsed time.

The statuses#

StatusMeaningWhat moves it on
scheduledA future-dated booking, held out of assignment until its time comes.The dispatch sweep, at the scheduled time. Not reachable from the v1 API today.
pendingCreated and waiting for a rider. Every API booking starts here.Automatic assignment, or an operator in the dashboard.
offeredOffered to one or more riders, none has taken it yet.A rider accepting, or the offer expiring and being re-broadcast.
assignedA rider now holds the job.The rider collecting the parcel.
acceptedThe rider confirmed. A legacy alias of assigned — treat the two the same.The rider collecting the parcel.
picked_upThe parcel is with the rider.The rider setting off.
in_transitOn the way to the drop-off.Delivery, confirmed at the door.
deliveredDone. Terminal.Nothing.
cancelledCalled off. Terminal. Any unsettled ledger entry is reversed.Nothing.

Treat unknown statuses as 'in progress'

Branch on the statuses you care about and let anything else fall through to a neutral "in progress" state. New statuses are additive, and a client that throws on one it has not seen turns our small change into your outage.

The cancellation window#

A delivery can be cancelled through the API while it is pending, scheduled, assigned or accepted — that is, up to the moment a rider physically has the parcel. After pickup the API refuses with 422, because the parcel is in the world and pretending otherwise in software would leave the record and reality disagreeing. Those cancellations go through the dispatch company's own operations.

Cancelling something already cancelled succeeds rather than erroring — see Cancel a delivery.

The event timeline#

Retrieving a delivery returns every event in order, oldest first. This is the honest record of what happened and when — better material for a customer-facing tracker than a status word on its own.

events
"events": [
  { "status": "pending",    "note": "Booking created via API",        "created_at": "2026-09-20T09:14:02.118Z" },
  { "status": "assigned",   "note": "Assigned to Musa I.",            "created_at": "2026-09-20T09:14:47.902Z" },
  { "status": "accepted",   "note": "Rider accepted the delivery",    "created_at": "2026-09-20T09:15:20.551Z" },
  { "status": "picked_up",  "note": "Parcel collected",               "created_at": "2026-09-20T09:31:08.310Z" },
  { "status": "in_transit", "note": "On the way to the drop-off",     "created_at": "2026-09-20T09:31:44.007Z" },
  { "status": "delivered",  "note": "Delivered, OTP confirmed",       "created_at": "2026-09-20T09:58:12.664Z" }
]
  • status — the status the delivery moved into.
  • note — a human sentence, sometimes naming the rider. Display it; never parse it.
  • created_at — ISO 8601, UTC.

Following a delivery#

There are no webhooks yet, so you poll. The rule of thumb: poll in proportion to how fast the thing can change.

polling
// Poll while it matters, stop when it does not.
const TERMINAL = new Set(["delivered", "cancelled"]);

async function follow(trackingCode) {
  for (;;) {
    const d = await dispatch.getDelivery(trackingCode);
    await onUpdate(d);
    if (TERMINAL.has(d.status)) return d;
    // In flight: 30s. Waiting for a rider: slower is fine.
    await sleep(d.status === "pending" ? 60_000 : 30_000);
  }
}
StateSuggested interval
pending60s — it is waiting on a human decision.
Anything in flight30s.
deliveredStop.
cancelledStop.

Give your customer the tracking page

Every delivery has a public tracking page keyed by its tracking_code, with live rider position once a rider is carrying the parcel. Linking to it is usually better than rebuilding it — and it costs you no polling at all.

Delivery confirmation

Deliveries are confirmed at the door with a one-time code sent to the recipient. If you send a dropoff_email on the booking, the recipient receives the code directly; otherwise it reaches them through the dispatch company. The code is never returned by the API — a code that can be read over the API is not evidence that anybody was at the door.

How a rider is chosen#

Assignment is ours to worry about, but two behaviours are worth knowing because they show up in your data:

  • Online bookings are not assigned until payment is confirmed. A delivery sitting at pending with payment_status: "unpaid" is waiting on money, not on riders. See Payments.
  • An offer can bounce. A rider who does not respond releases the job, which returns to pending and is offered again. A delivery moving backwards from offered to pending is normal, not an error.