Booking lifecycle & confirmations

The booking state machine is where ops discipline lives. This article covers each state, its entry conditions, who can transition, and common mistakes.

The full state machine

draft → requested → confirmed → locked → planned → in_transit → delivered
                                                               → cancelled

Plus:

• From any state except delivered / cancelled: hold flag (not a separate state, a superimposed flag).
• cancelled is terminal except for admin-reactivation via a new revision.

State-by-state

draft

Created manually, not yet sent for customer confirmation. Commercial terms may still be incomplete.

• Enter: Creating a new booking via "+ Create" in Bookings, or during a manual booking path bypassing the quote flow.
• Exit: Transition to requested when sent for customer confirmation.

requested

Customer has confirmed intent; ops is awaiting final carrier booking and paperwork.

• Enter: Quote acceptance (via public link or manual Convert to Booking). Or manually from draft → Request Confirmation.
• Exit: Transition to confirmed when carrier booking is in hand.
• Role: operator and above can create/move to requested.

confirmed

Carrier agrees; documents can be issued; invoicing can start.

• Enter: Operator clicks Confirm on a requested booking.
• Exit: Transition to locked when BL/AWB is issued; or to cancelled if the deal falls through.
• Role: operator or manager confirms. Disputes (customer vs carrier mismatch) may require manager approval in future versions.
• Side effects: auto-creates the linked Shipment (sea/air) or RoadTrip (road); milestones populate.

locked

Master document (MBL / MAWB) has been issued. Commercial terms are fixed.

• Enter: Operator clicks Lock after issuing the BL/AWB.
• Exit: planned (cargo pickup scheduled) or cancelled (carrier cancellation — rare after lock).
• Amendments: use New Revision; the original stays, a dated revision records the change.

planned

Pickup is scheduled; cargo is about to move.

• Enter: First pickup milestone or manual transition.
• Exit: in_transit when cargo departs origin.

in_transit

Cargo is moving.

• Enter: Departure milestone (physical event).
• Exit: delivered when POD is received.

delivered

POD received; operational execution complete.

• Enter: Delivery milestone (POD / arrival confirmation).
• Final-stage actions: invoicing, vendor bill reconciliation, margin close.
• Exit: none (terminal).

cancelled

Booking killed before completion.

• Enter: Cancel button (role-gated: manager+).
• Side effects: any charges already posted need explicit reversal (Credit Note against the customer invoice; AP adjustment against vendor bills). CargoSurge doesn't auto-reverse — that's accounting hygiene.

The hold flag

Any active booking can be flagged "on hold" (from booking detail → Hold). Adds:

• Hold reason — mandatory short text.
• Hold started at — timestamp.

Holds don't change the state — a held in_transit booking is still in_transit, just flagged. Resolving the hold clears the flag and populates hold_resolved_at.

Use holds for customer payment hold, customs hold, disputed charges — situations where operational execution is paused but the booking is not cancelled.

Transition rules — at a glance

From \ To	requested	confirmed	locked	planned	in_transit	delivered	cancelled
draft	✓	—	—	—	—	—	✓
requested	—	✓	—	—	—	—	✓
confirmed	—	—	✓	✓	—	—	✓
locked	—	—	—	✓	—	—	✓
planned	—	—	—	—	✓	—	✓
in_transit	—	—	—	—	—	✓	✓
delivered	—	—	—	—	—	—	—
cancelled	—	—	—	—	—	—	—

No state allows backwards movement. Use New Revision for amendments, Cancel + Re-create if the state really needs to reset.

Common pitfalls