Order lifecycle
Order status is controlled by one explicit state machine (order-state-machine.ts): 29 allowed transitions, each listing which parties may make it and which checks guard it. Nothing writes a status directly. Each seller's order group moves through these states independently.
Key rules
- Cancellation is possible only before READY_FOR_PICKUP, and the buyer's own right to cancel ends as soon as a seller accepts. After pickup, the buyer's route is a return.
- Failed delivery can be retried up to 3 times; after that the order is cancelled.
- Delivered requires a validated proof of delivery (unless staff override).
- Returns can be requested for 14 days after delivery.
- COMPLETED is deliberately not final: a chargeback or late claim can reopen it as a dispute. Only CANCELLED and REFUNDED are final.
Three kinds of "no"
| Error code | Meaning |
|---|---|
order.ILLEGAL_TRANSITION | The move does not exist (e.g. PAID → DELIVERED). |
auth.FORBIDDEN | The move exists but this party may not make it (a buyer cannot mark their own order paid). |
order.CANCELLATION_WINDOW_CLOSED, order.RETURN_WINDOW_CLOSED, delivery.PROOF_INVALID | The move is allowed in principle, but a guard failed. |
Who may make each transition
"Staff" means admins and super admins.
| Transition | Who may make it |
|---|---|
PENDING_PAYMENT → PAID / PAYMENT_FAILED | System (payment result) |
PAYMENT_FAILED → PENDING_PAYMENT | Buyer, system (retry) |
PAID → CONFIRMED → PROCESSING → READY_FOR_PICKUP | Seller, staff |
… → CANCELLED (before pickup) | Buyer (only until a seller accepts), seller, system, staff |
READY_FOR_PICKUP → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY | Driver, system, staff |
OUT_FOR_DELIVERY → DELIVERED | Driver (with validated proof), staff |
OUT_FOR_DELIVERY → FAILED_DELIVERY | Driver, system, staff |
FAILED_DELIVERY → OUT_FOR_DELIVERY / CANCELLED | Dispatcher, system, staff |
DELIVERED → COMPLETED | System, staff |
DELIVERED → RETURN_REQUESTED | Buyer (within 14 days), staff |
RETURN_REQUESTED → RETURN_APPROVED | Seller, staff |
RETURN_REQUESTED → DISPUTED | Seller, buyer, staff |
RETURN_APPROVED → RETURN_IN_TRANSIT | Buyer, driver, system, staff |
RETURN_IN_TRANSIT → RETURN_RECEIVED | Seller, staff |
RETURN_RECEIVED → REFUNDED | System, staff |
COMPLETED → DISPUTED | Buyer, staff |
DISPUTED → COMPLETED / REFUNDED | Staff only |
Worth knowing
The DELIVERED → COMPLETED move is defined for the system, but no scheduled job in the worker performs it today; orders remain DELIVERED until staff complete them. Returns and reviews treat DELIVERED and COMPLETED alike.