# Shipment State Machine
Every parcel dispatched through the Tumr network moves through a deterministic state machine:
[ DRAFT ] ──> [ PENDING ] ──> [ ASSIGNED ] ──> [ PICKED_UP ] ──> [ IN_TRANSIT ] ──> [ ARRIVED ] ──> [ COMPLETED ]
│ │ │ │ ▲
│ │ │ ┌──> [ AT_PICKUP_POINT ] ───┘ │
│ │ │ │ │
│ │ └───────┴──> [ EXCEPTION ] │
▼ ▼ │
[ CANCELLED ] [ CANCELLED ] │
(Escrow Refund) (Escrow Refund) │
│
(Recipient verified with 6-digit OTP) ────────────────────────────────────────────────────────┘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 merchant escrow hold. |
| ASSIGNED | Courier claimed dispatch via QR scan or carrier dispatch. | Fare held in escrow. |
| PICKED_UP | Driver arrived at pickup location and collected parcel. | Escrow hold maintained. |
| IN_TRANSIT | Package is actively moving toward recipient dropoff. | GPS telemetry active. |
| ARRIVED | Courier reached dropoff location, awaiting recipient OTP. | Escrow hold maintained. |
| AT_PICKUP_POINT | Parcel held safely at retail pickup point (D42 network). | Escrow hold maintained. |
| COMPLETED | Recipient validated 6-digit delivery OTP code. | Escrow released: Carrier/rider credited, commission settled. |
| CANCELLED | Order cancelled by merchant before pickup. | Escrow unlocked: 100% refunded to merchant available balance. |
| EXCEPTION | Delivery aborted (unreachable customer, wrong address, damage). | Handled via carrier dispute resolution or return to sender. |