Commerce API - Flow Diagram

%%{init: { "theme": "base", "themeVariables": { "fontSize": "18px", "background": "transparent", "actorBkg": "#038851", "actorTextColor": "#ffffff", "actorBorder": "#026139", "actorLineColor": "#94a3b8", "signalColor": "#64748b", "signalTextColor": "#059669", "noteBkgColor": "#e6f4ee", "noteTextColor": "#02502f", "noteBorderColor": "#038851", "activationBkgColor": "#c6ebdc", "activationBorderColor": "#026139", "sequenceNumberColor": "#ffffff" }, "sequence": { "useMaxWidth": true, "actorMargin": 70, "width": 150, "height": 60, "boxMargin": 12, "noteMargin": 14, "messageMargin": 50, "diagramMarginX": 20, "diagramMarginY": 20, "actorFontSize": 18, "actorFontWeight": 700, "noteFontSize": 15, "noteFontFamily": "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace", "messageFontSize": 16, "messageFontWeight": 700, "noteAlign": "left", "mirrorActors": false } }}%%
sequenceDiagram
    autonumber
    actor Customer
    participant Platform as Commerce Platform<br/>(ordering app/site)
    participant Deliverect
    participant Pay as Deliverect Pay / PSP
    participant POS

    Note over Platform,Deliverect: 1. Store & Menu Discovery
    Customer->>Platform: Opens ordering app
    Platform->>Deliverect: GET /stores (location, fulfilment type)
    Deliverect-->>Platform: Nearby stores (sorted by distance)
    Platform->>Deliverect: GET /stores/{storeId}
    Deliverect-->>Platform: Store details (storeId, menuIds)
    Platform->>Deliverect: GET /stores/{storeId}/menus
    Deliverect-->>Platform: Menu (categories, items, prices, images)

    Note over Platform,Deliverect: 2. Basket Creation & Build-up
    Customer->>Platform: Selects items / fulfilment type
    Platform->>Deliverect: POST /baskets (fulfilment type)
    Deliverect-->>Platform: basketId
    loop As customer edits order
        Platform->>Deliverect: PATCH /baskets/{basketId}/items<br/>(+ /customer, /discounts, /charges, /payment)
        Deliverect-->>Platform: Recalculated basket (totals, taxes, fees)
    end

    Note over Platform,Pay: 3. Payment (optional / method-dependent)
    alt Deliverect Pay (DPay)
        Platform->>Deliverect: Request payment (Pay API)
        Deliverect->>Pay: Create payment intent
        Pay-->>Deliverect: Redirect link
        Deliverect-->>Platform: Payment redirect link
        Customer->>Pay: Completes payment
        Pay->>Deliverect: Payment authorized
        Deliverect->>Platform: POST paymentUpdate webhook (status=authorized)
    else Third party / unpaid
        Note right of Platform: External PSP,<br> or set isPrepaid=false<br/>(order injected as unpaid)
    end

    Note over Platform,POS: 4. Checkout & POS Injection
    Platform->>Deliverect: POST /v2/checkouts (payment method,<br/>channelOrderId, order notes)
    Deliverect-->>Platform: 200 OK (checkout received)
    Deliverect->>POS: Inject order into POS
    Deliverect->>Platform: POST checkoutUpdate webhook (status=completed / failed)
    Note right of Platform: Treat as successful<br> only on<br/>"status": "completed"

    Note over Platform,POS: 5. Ongoing Webhooks (POS / store -> Platform)
    POS->>Deliverect: Order status change
    Deliverect->>Platform: POST orderStatusUpdate webhook
    Deliverect->>Platform: POST courierStatusUpdate webhook (delivery updates)
    Deliverect->>Platform: POST menuUpdate webhook (menu published)
    Deliverect->>Platform: POST snooze/unsnooze webhook (item availability)
    Deliverect->>Platform: POST busyMode webhook (store open/closed)
    Platform-->>Deliverect: 200 OK (per webhook)