Delivery states

A delivery job moves only along the paths below. Any other move is refused with INVALID_DELIVERY_STATE, and every move is checked against the job as the database holds it at that moment, then written with an event in the job's history.

These are the internal states that the API returns as status. People see the simpler tracking statuses instead. Relays between riders are not states: the delivery keeps its state while custody passes from one rider to another.

States

State	Meaning
PENDING_DELIVERY	Booked and priced; not yet released to dispatch.
DELIVERY_REQUESTED	Released to dispatch; IDM is looking for a rider.
OFFERED	An offer is open to a rider and has not been answered yet.
ASSIGNED	A rider accepted and is heading to the pickup.
ARRIVED_AT_PICKUP	The rider is at the pickup, waiting for the sender to hand over.
PICKED_UP	The sender confirmed the handover; the rider has the item.
ON_THE_WAY	The rider is travelling to the drop-off.
ARRIVED_AT_DESTINATION	The rider is at the drop-off, waiting for the recipient.
RECEIPT_CONFIRMED	The recipient confirmed receipt; the rider completes the delivery next.
DELIVERED	Completed. The end state of a successful delivery.
CANCELLED	Cancelled before pickup. An end state.
DELIVERY_EXCEPTION	Something stopped the delivery; an operator or the system resolves it.
RECOVERY_REQUIRED	Being recovered: it goes back to dispatch without changing its original facts.
FAILED	Ended without reaching the recipient. An end state.

Allowed moves

From	To	Who can make it
PENDING_DELIVERY	DELIVERY_REQUESTED	Tenant (API), Sender
DELIVERY_REQUESTED	OFFERED	IDM, Operator, Delivery company
OFFERED	ASSIGNED	Rider
OFFERED	DELIVERY_REQUESTED	IDM
ASSIGNED	ARRIVED_AT_PICKUP	Rider
ARRIVED_AT_PICKUP	PICKED_UP	Sender
PICKED_UP	ON_THE_WAY	Rider
ON_THE_WAY	ARRIVED_AT_DESTINATION	Rider
ARRIVED_AT_DESTINATION	RECEIPT_CONFIRMED	Recipient
RECEIPT_CONFIRMED	DELIVERED	Rider, Operator, Tenant (API)
DELIVERY_EXCEPTION	RECOVERY_REQUIRED	Operator, IDM
DELIVERY_EXCEPTION	ON_THE_WAY	Operator, IDM
DELIVERY_EXCEPTION	FAILED	Operator, IDM
RECOVERY_REQUIRED	DELIVERY_REQUESTED	IDM
PENDING_DELIVERY, DELIVERY_REQUESTED, OFFERED, ASSIGNED, ARRIVED_AT_PICKUP	CANCELLED	Tenant (API), Sender, Operator
ASSIGNED, ARRIVED_AT_PICKUP, PICKED_UP, ON_THE_WAY, ARRIVED_AT_DESTINATION	DELIVERY_EXCEPTION	Rider, Delivery company, Operator, IDM
ASSIGNED, ARRIVED_AT_PICKUP	DELIVERY_REQUESTED	IDM

What the moves mean in practice

• Only an accepted offer assigns a rider. No delivery is ever given to a rider who did not accept it.
• Handover is the sender's act. PICKED_UP happens only when the sender confirms it.
• Receipt is the recipient's act. RECEIPT_CONFIRMED happens only from the recipient's own secure link.
• Cancellation stops at pickup. After the item is with a rider, the way forward is an exception and recovery, never cancellation.
• Recovery never rewrites history. Places, vehicle, price and earlier events stay as they were; recovery adds events.