Shipment State Machine
Understand the lifecycle states, transitions, and automated escrow triggers.
Every parcel dispatched through the Tumr network moves through a deterministic state machine:
[ DRAFT ] ──> [ PENDING ] ──> [ PICKED_UP ] ──> [ IN_TRANSIT ] ──> [ ARRIVED ] ──> [ COMPLETED ]
│ │
│ ┌──> [ AT_PICKUP_POINT ] ──> [ COMPLETED ]
│ │(COMPLETED: recipient verified with 6-digit OTP, escrow released) ```
State Definitions
| State | Description | Financial Action |
| :--- | :--- | :--- |
| DRAFT | Shipment created but held prior to broadcast. | No escrow reserved. |
| PENDING | Order dispatched. Awaiting rider claim or carrier assignment. | Fare reserved in escrow hold. |
| PICKED_UP | Rider arrived at pickup location and collected the parcel. | Escrow hold maintained. |
| IN_TRANSIT | Package is actively moving toward the recipient. | GPS telemetry active. |
| ARRIVED | Rider reached the dropoff location, awaiting recipient OTP. | Escrow hold maintained. |
| AT_PICKUP_POINT | Parcel held at a pickup point awaiting collection. | Escrow hold maintained. |
| COMPLETED | Delivery verified (recipient OTP or confirmed handover). | Escrow released: rider/carrier credited, commission settled. |
| EXCEPTION | Delivery aborted (unreachable customer, wrong address, damage). | Routed to dispute resolution or return flow. |
| RETURNING_TO_SENDER / RETURN_TO_SENDER | Parcel is being returned to the sender. | Escrow handling follows the dispute outcome. |