Order Lifecycle

This page details the complete order lifecycle from creation to completion, including all state transitions and process flows.

Order State Machine

stateDiagram-v2
    [*] --> DRAFT: Create Order

    DRAFT --> SENT: Submit to Customer
    DRAFT --> CANCELLED: Cancel

    SENT --> CONFIRMED: Customer Accepts
    SENT --> DRAFT: Revise Order
    SENT --> CANCELLED: Customer Rejects

    CONFIRMED --> PROCESSING: Start Processing
    CONFIRMED --> CANCELLED: Cancel Before Processing

    PROCESSING --> FULFILLED: Items Ready
    PROCESSING --> PARTIALLY_FULFILLED: Partial Ready
    PROCESSING --> CANCELLED: Cancel During Processing

    PARTIALLY_FULFILLED --> FULFILLED: Remaining Items Ready
    PARTIALLY_FULFILLED --> CANCELLED: Cancel Remaining

    FULFILLED --> SHIPPED: Hand to Carrier
    FULFILLED --> CANCELLED: Cancel Before Shipping

    SHIPPED --> DELIVERED: Delivery Confirmed
    SHIPPED --> EXCEPTION: Delivery Issue

    EXCEPTION --> SHIPPED: Retry Delivery
    EXCEPTION --> RETURNED: Return to Sender

    DELIVERED --> COMPLETED: Close Order
    RETURNED --> REFUNDED: Process Refund

    COMPLETED --> [*]
    CANCELLED --> [*]
    REFUNDED --> [*]

    note right of DRAFT
        Initial state
        Cart or manual entry
    end note

    note right of CONFIRMED
        Payment captured or
        credit approved
    end note

    note right of FULFILLED
        All items picked
        and packed
    end note

Order Status Descriptions

Status	Description	Allowed Actions
`DRAFT`	Order created, not yet submitted	Edit, Submit, Cancel
`SENT`	Sent to customer for approval	Revise, Confirm, Cancel
`CONFIRMED`	Customer accepted, payment captured	Process, Cancel
`PROCESSING`	Being picked and packed	Complete, Partial, Cancel
`PARTIALLY_FULFILLED`	Some items ready	Complete remaining, Cancel
`FULFILLED`	All items ready for shipping	Ship, Cancel
`SHIPPED`	Handed to carrier	Track, Mark Delivered
`DELIVERED`	Confirmed delivery	Close
`COMPLETED`	Order closed	None (final)
`CANCELLED`	Order cancelled	None (final)
`EXCEPTION`	Delivery issue	Retry, Return
`RETURNED`	Returned to sender	Refund
`REFUNDED`	Refund processed	None (final)

Order Creation Sequence

sequenceDiagram
    participant User
    participant UI as Frontend
    participant API as TRPC Router
    participant Service as Order Service
    participant Stock as Inventory Service
    participant DB as Database
    participant Payment as Payment Service

    User->>UI: Add items to cart
    UI->>API: createOrder(items)
    API->>Service: createOrder(ctx, items)

    Service->>Stock: checkAvailability(items)
    Stock->>DB: Query stock levels
    DB-->>Stock: Stock data
    Stock-->>Service: Availability result

    alt Insufficient Stock
        Service-->>API: Error: Items unavailable
        API-->>UI: Show stock error
    else Stock Available
        Service->>Stock: reserveStock(items)
        Stock->>DB: Create reservations
        DB-->>Stock: Reservations created

        Service->>DB: Create order record
        DB-->>Service: Order created

        Service->>DB: Create order items
        DB-->>Service: Items created

        Service-->>API: Order (DRAFT status)
        API-->>UI: Show order summary
    end

    User->>UI: Proceed to checkout
    UI->>API: submitOrder(orderId)
    API->>Service: submitOrder(orderId)

    Service->>Payment: initializePayment(order)
    Payment-->>Service: Payment intent

    Service->>DB: Update status to SENT
    DB-->>Service: Updated

    Service-->>API: Order with payment intent
    API-->>UI: Redirect to payment

Payment Confirmation Sequence

sequenceDiagram
    participant Payment as Payment Gateway
    participant Webhook as Webhook Handler
    participant Service as Order Service
    participant Stock as Inventory Service
    participant Email as Email Service
    participant DB as Database

    Payment->>Webhook: payment.succeeded event
    Webhook->>Service: handlePaymentSuccess(paymentId)

    Service->>DB: Find order by paymentIntentId
    DB-->>Service: Order data

    Service->>DB: Update status to CONFIRMED
    Service->>DB: Record payment transaction
    DB-->>Service: Updated

    Service->>Stock: confirmReservations(orderId)
    Stock->>DB: Update stock status
    DB-->>Stock: Updated

    Service->>Email: sendOrderConfirmation(order)
    Email-->>Service: Queued

    Service-->>Webhook: Success response
    Webhook-->>Payment: 200 OK

Order Fulfillment Sequence

sequenceDiagram
    participant Staff as Warehouse Staff
    participant UI as Fulfillment UI
    participant API as TRPC Router
    participant Service as Fulfillment Service
    participant Stock as Inventory Service
    participant Ship as Shipping Service
    participant DB as Database

    Staff->>UI: View pending orders
    UI->>API: listOrdersForFulfillment()
    API->>Service: getOrdersToFulfill(ctx)
    Service->>DB: Query CONFIRMED orders
    DB-->>Service: Orders list
    Service-->>API: Orders
    API-->>UI: Display orders

    Staff->>UI: Start picking order
    UI->>API: startFulfillment(orderId)
    API->>Service: startFulfillment(orderId)
    Service->>DB: Update to PROCESSING
    Service->>DB: Create fulfillment record
    DB-->>Service: Created
    Service-->>API: Fulfillment started
    API-->>UI: Show pick list

    loop For each item
        Staff->>UI: Mark item picked
        UI->>API: markItemPicked(itemId)
        API->>Service: updateFulfillmentItem(itemId)
        Service->>DB: Update item status
        DB-->>Service: Updated
    end

    Staff->>UI: Complete picking
    UI->>API: completePicking(fulfillmentId)
    API->>Service: completePicking(fulfillmentId)

    Service->>Stock: decrementStock(items)
    Stock->>DB: Update stock levels
    DB-->>Stock: Updated

    Service->>Ship: createShipment(order)
    Ship->>DB: Create shipment record
    Ship-->>Service: Shipment created

    Service->>DB: Update to FULFILLED
    DB-->>Service: Updated

    Service-->>API: Fulfillment complete
    API-->>UI: Ready for shipping

Order Cancellation Flow

flowchart TD
    START[Cancel Request] --> CHECK{Order Status?}

    CHECK -->|DRAFT| CANCEL_DRAFT[Cancel Draft]
    CHECK -->|SENT| CANCEL_SENT[Cancel Sent]
    CHECK -->|CONFIRMED| CHECK_PAYMENT{Payment Captured?}
    CHECK -->|PROCESSING| CHECK_PROGRESS{Items Picked?}
    CHECK -->|FULFILLED| CHECK_SHIPPED{Shipped?}
    CHECK -->|SHIPPED+| CANNOT_CANCEL[Cannot Cancel]

    CANCEL_DRAFT --> RELEASE_RESERVE[Release Stock Reservations]
    CANCEL_SENT --> RELEASE_RESERVE

    CHECK_PAYMENT -->|Yes| INIT_REFUND[Initiate Refund]
    CHECK_PAYMENT -->|No| RELEASE_RESERVE

    INIT_REFUND --> RELEASE_RESERVE

    CHECK_PROGRESS -->|Yes| RETURN_STOCK[Return Picked Items]
    CHECK_PROGRESS -->|No| RELEASE_RESERVE

    RETURN_STOCK --> INIT_REFUND

    CHECK_SHIPPED -->|No| RETURN_STOCK
    CHECK_SHIPPED -->|Yes| CANNOT_CANCEL

    RELEASE_RESERVE --> UPDATE_STATUS[Update to CANCELLED]
    UPDATE_STATUS --> NOTIFY[Send Cancellation Email]
    NOTIFY --> LOG[Log Cancellation]
    LOG --> COMPLETE[Cancellation Complete]

    CANNOT_CANCEL --> SUGGEST[Suggest Return Process]

    style CANNOT_CANCEL fill:#ffebee
    style COMPLETE fill:#e8f5e9

Order Type Variations

Delivery Order Flow

flowchart LR
    ORDER[Order Created] --> CONFIRM[Confirmed]
    CONFIRM --> FULFILL[Fulfilled]
    FULFILL --> SHIP[Shipped]
    SHIP --> DELIVER[Delivered]
    DELIVER --> COMPLETE[Completed]

    style ORDER fill:#e1f5fe
    style COMPLETE fill:#e8f5e9

Pickup Order Flow

flowchart LR
    ORDER[Order Created] --> CONFIRM[Confirmed]
    CONFIRM --> READY[Ready for Pickup]
    READY --> PICKUP[Customer Picks Up]
    PICKUP --> COMPLETE[Completed]

    style ORDER fill:#e1f5fe
    style COMPLETE fill:#e8f5e9

Digital Delivery Flow

flowchart LR
    ORDER[Order Created] --> CONFIRM[Confirmed]
    CONFIRM --> GENERATE[Generate Access]
    GENERATE --> DELIVER[Send Download Link]
    DELIVER --> COMPLETE[Completed]

    style ORDER fill:#e1f5fe
    style COMPLETE fill:#e8f5e9

Order Events Timeline

gantt
    title Order Processing Timeline
    dateFormat HH:mm
    axisFormat %H:%M

    section Order
    Created (DRAFT)           :milestone, m1, 09:00, 0m
    Submitted (SENT)          :milestone, m2, 09:05, 0m
    Confirmed (CONFIRMED)     :milestone, m3, 09:10, 0m

    section Fulfillment
    Processing Started        :milestone, m4, 09:30, 0m
    Picking                   :active, pick, 09:30, 30m
    Packing                   :pack, after pick, 15m
    Fulfilled                 :milestone, m5, 10:15, 0m

    section Shipping
    Label Generated           :milestone, m6, 10:20, 0m
    Shipped                   :milestone, m7, 11:00, 0m
    In Transit                :transit, 11:00, 480m
    Delivered                 :milestone, m8, 19:00, 0m

    section Completion
    Completed                 :milestone, m9, 19:05, 0m

Error Handling States

stateDiagram-v2
    [*] --> Normal: Order Processing

    Normal --> PaymentError: Payment Failed
    Normal --> StockError: Stock Unavailable
    Normal --> FulfillmentError: Picking Issue
    Normal --> ShippingError: Carrier Error

    PaymentError --> Normal: Retry Payment
    PaymentError --> Cancelled: Max Retries

    StockError --> Normal: Stock Replenished
    StockError --> PartialFulfill: Partial Available
    StockError --> Cancelled: Customer Cancels

    FulfillmentError --> Normal: Issue Resolved
    FulfillmentError --> Cancelled: Cannot Fulfill

    ShippingError --> Normal: Retry Shipping
    ShippingError --> Exception: Persistent Issue

    state Exception {
        [*] --> InvestigateIssue
        InvestigateIssue --> RetryDelivery
        InvestigateIssue --> ReturnToSender
        RetryDelivery --> Delivered
        ReturnToSender --> Refund
    }

Order Lifecycle

On this page