Shipment Lifecycle

Every shipment moves through a state machine. The same statuses cover both same-city and regional deliveries — only the path differs.

State machine

PENDING
   │   (transient — only seen if you use gateway payment instead of wallet)
   ▼
CONFIRMED                    payment cleared, dispatch starts
   │
   ▼
PICKUP_DISPATCHED            first-mile rider assigned, heading to sender
   │
   ▼
PICKED_UP                    rider has the package
   │
   ├── (same-city) ──────────┐
   │                         │
   ▼ (regional)              │
IN_TRANSIT                   │  hub-to-hub transit leg
   │                         │
   ▼                         ▼
                OUT_FOR_DELIVERY  last-mile rider heading to receiver
                         │
                         ▼
                    DELIVERED  ✅

Terminal states: DELIVERED, CANCELLED, FAILED.

Status reference

Status	Meaning	What happens
pending	Just created, awaiting payment	For wallet shipments, this exists only for a fraction of a second before flipping to confirmed
confirmed	Payment received	Auto-dispatch begins — engine picks the nearest available rider
pickup_dispatched	Rider assigned	Rider has the job in their app and is heading to the sender
picked_up	Rider has the package	Sender's part is done
in_transit	Regional only — hub-to-hub	Package is on our transit network between cities
out_for_delivery	Last-mile rider heading to receiver	Final leg
delivered	Successfully delivered	Terminal — proof-of-delivery captured
cancelled	Cancelled before pickup	Wallet refunded
failed	Dispatch or delivery attempts exhausted	Returned or held for resolution. Wallet refunded if the package never moved.

Stuck in confirmed?

If no rider is in range at the time of payment, the shipment stays at confirmed and our dispatcher retries automatically on a schedule for a while before giving up and marking the shipment failed. You don't need to poll or re-create — just listen for delivery.picked_up or delivery.failed. If you see frequent failed results from no-rider situations, talk to support about expanding coverage in that area.

Same-city vs regional

Status	Same-city	Regional
pending	✓	✓
confirmed	✓	✓
pickup_dispatched	✓	✓
picked_up	✓	✓
in_transit	— (skipped)	✓
out_for_delivery	✓	✓
delivered	✓	✓

Same-city shipments go directly from picked_up → out_for_delivery. Regional shipments pass through in_transit while the package moves between sorting hubs.

Journey legs

Each shipment has 1 or 3 legs — segments handled by different actors:

Leg	Direction	Handled by	Used in
first_mile	Sender → origin hub (or full route for same-city)	Rider	Both
transit	Origin hub → destination hub	Dodo transit network	Regional only
last_mile	Destination hub → receiver	Rider	Regional only

Legs appear in the legs array of every shipment response. Each leg has its own status (pending, in_progress, completed, failed) so you can show progress per segment in your UI.

Hub sub-events (regional)

Regional shipments pass through sorting hubs. These don't change the top-level status but are recorded in the events array:

Event description	When
Shipment received at {hub_name}	Package checked in at origin hub
Package containerized for transit	Loaded onto an outgoing container
Container dispatched from {hub_name}	Transit container left origin hub
Container arrived at {hub_name}	Transit container arrived at destination hub
Last-mile rider assigned	Local rider picked up from destination hub

Use the events array on GET /merchant/shipments/{id} to surface fine-grained progress.

Webhook mapping

Each status transition fires a corresponding webhook. See Webhooks for payloads.

Transition	Event
→ confirmed	shipment.created, shipment.paid
→ pickup_dispatched	delivery.rider_assigned
(rider moving — no status change)	delivery.en_route_to_pickup
→ picked_up	delivery.picked_up
→ delivered	delivery.delivered
→ cancelled	shipment.cancelled
→ failed	delivery.failed

Cancellation rules

Cancellable from: pending, confirmed, pickup_dispatched. Cancellation fees are state-graded — see Manage Shipments → Cancel a shipment for the full fee table and the two-step preview/commit API.

Not cancellable from: picked_up, in_transit, out_for_delivery, delivered, cancelled, failed.

Once the rider has the package, create a return-to-sender shipment instead of cancelling.