Commerce API - Overview

Overview

Below is a high-level overview of the key Commerce API interactions, with a brief description of the role they play in supporting the complete ordering journey from store discovery through to POS order injection;

Discover Nearby Stores - GET /stores

Returns locations available, sorted by distance to user's current location and filtered by preferred fulfilment type

Select a Specific Store - GET /stores/{storeId}

Return locations available, sort by distance to user's current location and filter by preferred fulfilment type

Browse Menu Options- GET /stores/{storeId}/menus

Review the categories and options within the menu along with their pricing, images, description, metadata etc

Create a Basket and Choose a Fulfilment Type POST /baskets

Specify the fulfilment type of Delivery/Dispatch, Pickup, Eat-in or Curbside and stablishes fulfilment type and starts the order

Add items and other details to get updated order amount PATCH /baskets/{basketId}/items

Update the basket as the user selects items and with similar method update user data /customer, apply loyalty or coupons /discounts include tips /payment and other order fees via /charges

Capture Payment Pay API

Proceed to process payment via Deliverect's Pay API (optional)

Complete the Order POST v2/checkouts

Finalise the transaction and specify which payment method used, along with unique order identifier and any order notes to trigger POS order injection

Commerce Workflow

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'mainBkg': '#ffffff'}}}%%
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)