Orders

Remove a single item from an order. Disallowed when the item is already paid or has a settlement in progress.

Get all items that were split from an order item for bill splitting

Split an order item into multiple parts for bill splitting with equal pricing

Toggle takeaway status on a kitchen dispatch item

Set item_state to "aborted" on a kitchen dispatch item. Requires orders.void permission. Rejects when the parent tab has any purchases. When reasonCode is "other", reasonNote is required.

Set item_state to "aborted" on multiple kitchen dispatch items in one request. Items may span multiple parent dispatches; one order.reversed event is emitted per affected KD. Requires orders.void permission. Rejects when ANY affected tab has purchases. When reasonCode is "other", reasonNote is required.

Retrieve a paginated list of orders with filtering capabilities.

Hybrid Dual-Fetch Architecture:

• PostgreSQL for recent orders (<30 minutes old) - ensures freshness
• BigQuery for historical orders (>30 minutes old) - scalability
• Automatic merge when date range spans both sources

KDS/Real-Time Mode:

• Use forcePostgres=true to always query PostgreSQL only
• This ensures fresh state data for Kitchen Display Systems
• Recommended for any real-time display needing immediate state updates

Default Behavior:

• Returns last 24 hours if no date filters specified
• Sorted by created_at descending (newest first)
• Items not included by default (use includeItems=true)

Performance Notes:

• BigQuery queries typically take 1-3 seconds
• For real-time displays, use forcePostgres=true or /api/v1/orders/stream endpoint

Permissions: 🔵 orders.read

Cancel a kitchen dispatch (order) by setting its state to aborted. Only early-stage orders can be cancelled.

Permissions: 🟠 inventory.update

Atomically void a set of existing kitchen_dispatch_items AND insert a set of new ones in ONE transaction, ONE webhook fan-out.

Cafe-mode "edit committed items" primitive. The earlier two-call shape (POST /void-batch + POST /append-to-dispatch in parallel) is replaced — clients describe the diff, the server applies it atomically.

Maps cleanly to actions:

• + on a committed line → { voids: [], inserts: [oneItem] }
• − on a committed line → { voids: [kdiId], inserts: [] }
• Variant edit → { voids: [originalKdiId], inserts: [newSpec] }

Guards:

• Dispatch must exist, belong to the supplied tab + location, and be in an appendable state (pending/accepted/in_preparation/ready_to_deliver).
• Tab must not be closed/abandoned.
• Voids: any tab purchase rejects with 422 TAB_HAS_PAYMENTS. Already-aborted items pass through (idempotent, wasAlreadyAborted: true in the response).
• Voided items not on this dispatch reject with 404 KITCHEN_DISPATCH_ITEM_NOT_FOUND.
• Inserts: items + variants validated identically to /orders/create.

Side effects (one fan-out):

• order.reversed webhook (printer KORRBONG) — skipped when suppressKorrbong: true (cafe mode).
• order.updated webhook with changes.syncedLines (KDS / cross-device refetch).
• tab.updated webhook with changes.kitchenDispatchSynced (cashier tab refetch).
• inventory.updated per ministock change.
• Per-item kitchen_dispatch_item.voided platform_event for the audit trail.

Permissions: 🟢 inventory.create

Retrieve detailed information about a specific order including all items.

Items are always included in the response for single order queries.

Permissions: 🔵 orders.read

Advance item-level states for a kitchen dispatch (order).

Item-Level State Tracking:

• Each item independently tracks its own state
• The overall order state is automatically derived as the earliest non-not_sent item state
• Forward-only: items can only advance forward, never backward

Filtering Options:

• No filter: advance ALL items in the order
• printerGroupId: advance only items in a specific prep group
• coursingOrder: advance only items in a specific course

Valid Target States:

• pending, accepted, in_preparation, ready_to_deliver, delivered, rejected

Webhook:

• Emits order.updated with targetItemState and optional printerGroupId

Permissions: 🟠 inventory.update

Edit item quantities on a kitchen dispatch in staged_awaiting_payment state.

Replaces the cancel→re-commit pattern previously used for storefront-web pay_upfront tab editing.

Per item:

• quantityCents > 0 — UPDATE quantity, adjust ministock delta
• quantityCents === 0 — DELETE the item (and its children), restore ministock

Guards:

• Dispatch must be in staged_awaiting_payment state
• No item on the dispatch may have paid_amount > 0
• Ministock checked for quantity increases
• Location access validated

Side effects:

• Tab total recalculated
• Emits order.updated webhook

Permissions: 🟠 inventory.update

Update the status of a kitchen dispatch item or modification. Requires staff authentication (JWT). User ID for audit trail is extracted from the auth token.

Get the status change history for a kitchen dispatch item

Batch update the status of multiple kitchen dispatch items and/or modifications. Requires staff authentication (JWT). User ID for audit trail is extracted from the auth token.

Update the state of a specific serving center for an order.

Serving Center State Management:

• Each serving center independently tracks its state for each order
• The overall order state is derived as the earliest (most backward) state across all serving centers
• When all serving centers advance, the overall order state advances too

Valid Serving Center States (forward-only):

• pending → accepted → in_preparation → ready_to_deliver → delivered
• rejected (terminal)

Constraints:

• Cannot set serving center state earlier than the overall order state
• Forward-only transitions (can't go backward)

Webhook:

• Emits order.updated with servingCenterId and servingCenterState
• Used by common-functions to send serving center SMS notifications

Replaces: GraphQL mutation updateServingCenterKitchenDispatchState from Karma-Merchant-API

Permissions: 🟠 inventory.update

Update the state of an order (kitchen dispatch).

Event Sourcing:

• Inserts an event into kitchen_dispatch_events table
• PostgreSQL trigger automatically updates kitchen_dispatches.latest_state
• Emits order.updated webhook for real-time UI updates

Valid State Transitions:

• not_sent → pending, delivered, aborted
• pending → accepted, rejected, aborted
• scheduled → accepted, pending, aborted
• accepted → in_preparation, ready_to_deliver, aborted
• in_preparation → ready_to_deliver
• ready_to_deliver → delivered
• rejected → rejected_and_acknowledged
• aborted → rejected_and_acknowledged (KDS bump on voided dispatch)
• staged_awaiting_payment → pending, aborted

Terminal States (no transitions):

• delivered, rejected_and_acknowledged

Idempotency:

• Calling with current state returns 200 success (no-op)
• Safe for retries in distributed systems

Permissions: 🟠 orders.update

Append items to an EXISTING kitchen_dispatch so they show up on the same KDS card the barista is already on.

Used by the cafe-mode "edit committed items" flow — instead of a void creating a fresh ticket, the cashier voids the original line and appends the replacement against the same dispatch ID.

Guards:

• Dispatch must exist and belong to the supplied tab.
• Dispatch state must be one of: pending, accepted, in_preparation, ready_to_deliver. Any other state (terminal, held, merged, staged) is rejected with 409 DISPATCH_NOT_APPENDABLE.
• Tab must not be closed/abandoned.
• Items + variants validated via the same path as /orders/create.

Side effects:

• New kitchen_dispatch_items inserted under the existing dispatch.
• Ministock decremented for items that track it.
• order.items_added webhook emitted (resource id = dispatch id).
• tab.updated webhook emitted with kitchenDispatchUpdated: { dispatchId, itemCount }.

Permissions: 🟢 inventory.create

Unified Order Creation API - handles all order creation from POS, Storefront, Kiosk, and QR code orders

Permissions: 🟢 inventory.create

Stream orders using Server-Sent Events for real-time displays.

Use Case: Kitchen Display Systems (KDS) and real-time dashboards where latency matters.

How It Works:

1. PostgreSQL results are sent first (~100ms) - recent orders
2. BigQuery results follow when ready (~1-3 seconds) - historical orders
3. Completion event sent when all data is received

SSE Events:

• postgres: Orders from PostgreSQL (recent data)
• bigquery: Orders from BigQuery (historical data)
• error: Error from a specific source
• complete: All data has been sent

Client Example:

Code
const eventSource = new EventSource('/api/v1/orders/stream?limit=1000')

eventSource.addEventListener('postgres', (e) => {
  const { orders } = JSON.parse(e.data)
  // Show recent orders immediately!
  setOrders(prev => mergeAndSort([...prev, ...orders]))
})

eventSource.addEventListener('bigquery', (e) => {
  const { orders } = JSON.parse(e.data)
  // Fill in historical orders
  setOrders(prev => mergeAndSort([...prev, ...orders]))
})

eventSource.addEventListener('complete', () => {
  eventSource.close()
})

Headers Required:

• Accept: text/event-stream
• X-Location-Id: {locationId}

Permissions: 🔵 orders.read

Fired when items are committed to the kitchen (POST /api/v1/inventory/commit). One event per dispatch.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired when items are added to a kitchen dispatch that already exists.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired on any KDS state transition or detail change. changes describes what shifted.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired when an order needs payment (e.g. INSTANT flow, or tab settlement).

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired when an order is marked complete in the KDS.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired when an order is cancelled. Includes the cancelling user and an optional reason.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired when a kitchen dispatch is reversed — e.g. void requested or booking unseated. Carries full item snapshots so subscribers (printer-service) can produce KORRBONG void tickets.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Fired in batches when item or modification statuses are updated (COMPLETED, UNAVAILABLE, or reset). Used by KDS UI for real-time updates.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.