Skip to content

Orders Domain

The orders domain handles the full lifecycle of a customer order, from cart to delivery/pickup completion.

Order Lifecycle

Cart -> Placed -> Confirmed -> Preparing -> Ready -> Completed
                                                  \-> Cancelled
                                                  \-> Refunded
  1. Cart -- Customer adds items via POST /users/{userId}/restaurants/{restaurantId}/cart
  2. Placed -- Customer submits the order via POST /restaurants/{restaurantId}/orders
  3. Confirmed -- Restaurant acknowledges the order
  4. Preparing -- Kitchen begins preparing the order (visible on KDS)
  5. Ready -- Order is ready for pickup or delivery
  6. Completed/Cancelled/Refunded -- Terminal states

Key Tables

Table Purpose
orderMaster Order headers: status, totals, timestamps, fulfillment type
orderDetail Line items: menu item, quantity, price, serving size
cart Active shopping carts per user per restaurant
order_status_changes Status transition audit trail (also replicated to lakehouse)

Cart

Each user has one cart per restaurant. Cart operations:

Endpoint Method Description
GET /users/{id}/restaurants/{id}/cart GET Get current cart
POST /users/{id}/restaurants/{id}/cart/cart-items POST Add item
PUT /users/{id}/restaurants/{id}/cart/cart-items/{id} PUT Update quantity
DELETE /users/{id}/restaurants/{id}/cart/cart-items/{id} DELETE Remove item

Cart items can include a servingQuantityId for multi-size items (e.g., selecting a 12" pizza instead of the default 8").

Order Totals

Order totals are calculated by the Yum API during order placement:

  • Subtotal -- Sum of (item price * quantity) for all line items
  • Tax -- Applied per tax rate, stored as a taxBreakdown JSONB array
  • Discounts -- Applied from active offers/loyalty rewards
  • Delivery fee -- For delivery orders
  • Total -- Final amount charged

Fulfillment Types

Type Description
Pickup Customer picks up from the restaurant
Delivery Restaurant or third-party delivers to the customer
Dine-in Customer orders from the table

Order Events

When an order is created or its status changes, Yum emits events to Redis Streams. These events are consumed by:

  • KDS-Web -- Real-time kitchen display
  • POS Adapters -- Sync to Clover POS
  • Lakehouse Writer -- Analytics pipeline (orders, order_items, order_status_changes tables)
  • Notifications service -- Customer + staff push notifications (see Notifications)

Delivery Integration

Delivery orders use orderType: "delivery" and reference a customer-supplied address. DoorDash webhook events (driver_assigned, driver_pickup, driver_en_route, delivery_completed) update order status and trigger push notifications to customers. See the Delivery domain page for the full integration status (webhook ingestion is live; outbound DoorDash creation API is pending).

Analytics

Order data flows to the lakehouse where it powers:

  • Revenue metrics (_metrics.revenue_daily)
  • Average order value (_metrics.aov_daily)
  • Fulfillment rate (_metrics.fulfillment_rate_daily)
  • Order phase timing (p50/p95 prep times)
  • Customer spending cohorts

Export/Import

Orders can be exported via yum/api/services/orderExportImport.ts for data migration and backup.

Key Files

  • yum/api/db/models/orderMaster.ts -- Order table definition
  • yum/api/db/models/orderDetail.ts -- Order line items
  • yum/api/services/orderService.ts -- Order business logic
  • yum/api/routes/ -- Order API endpoints
  • yum/api/schema/order.ts -- Zod validation schemas