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#
| Status | Meaning | What moves it on |
|---|---|---|
scheduled | A 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. |
pending | Created and waiting for a rider. Every API booking starts here. | Automatic assignment, or an operator in the dashboard. |
offered | Offered to one or more riders, none has taken it yet. | A rider accepting, or the offer expiring and being re-broadcast. |
assigned | A rider now holds the job. | The rider collecting the parcel. |
accepted | The rider confirmed. A legacy alias of assigned — treat the two the same. | The rider collecting the parcel. |
picked_up | The parcel is with the rider. | The rider setting off. |
in_transit | On the way to the drop-off. | Delivery, confirmed at the door. |
delivered | Done. Terminal. | Nothing. |
cancelled | Called off. Terminal. Any unsettled ledger entry is reversed. | Nothing. |
Treat unknown statuses as 'in progress'
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": [
{ "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.
// 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);
}
}| State | Suggested interval |
|---|---|
pending | 60s — it is waiting on a human decision. |
| Anything in flight | 30s. |
delivered | Stop. |
cancelled | Stop. |
Give your customer the tracking page
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
pendingwithpayment_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
pendingand is offered again. A delivery moving backwards fromofferedtopendingis normal, not an error.