Authenticated API

KDS endpoints require a valid JWT Bearer token with kitchen/chef roles. The API gateway exposes 6 KDS endpoints at /v1/commerce/kds/*.

Kitchen Display System (KDS) API

Comprehensive API for kitchen operations, including station management, ticket lifecycle, intelligent order routing, and AI-powered prep time estimation.

Base Path: /api/v1/kds

Overview

The KDS API provides:

Feature	Description
Station Management	CRUD operations for kitchen stations with 9 station types
Intelligent Routing	Menu item-to-station mapping with prep time rules
Ticket Lifecycle	7-state ticket workflow (Held -> Pending -> InProgress -> Ready -> Bumped)
Expo View	Aggregated order status for expediter station
Course Firing	Coordinate multi-course meal timing
AI Prep Time	ML-based prep time prediction using station load
Allergen Tracking	Allergen information flows through to tickets
Real-time Events	WebSocket events for ticket state changes

---

Station Types

The system supports 9 distinct station types:

Station	Code	Description	Example Items
Grill	grill	Grilled items	Burgers, steaks, grilled chicken
Fry	fry	Fried items	Fries, wings, fried fish
Prep	prep	Cold prep/salads	Salads, cold appetizers
Expo	expo	Order assembly	Final check station
Bar	bar	Beverages	Drinks, cocktails
Pizza	pizza	Pizza station	Pizzas, flatbreads
Salad	salad	Salad station	Salads, cold soups
Dessert	dessert	Dessert station	Desserts, pastries
Generic	generic	Custom/other	Any unclassified items

---

Ticket Lifecycle

┌────────┐     ┌─────────┐     ┌────────────┐     ┌───────┐     ┌────────┐
│  HELD  │────>│ PENDING │────>│ INPROGRESS │────>│ READY │────>│ BUMPED │
└────────┘     └─────────┘     └────────────┘     └───────┘     └────────┘
     │              │                │                │
     │              │                │                │
     v              v                v                v
┌────────────────────────────────────────────────────────────────────────┐
│                              VOIDED                                     │
└────────────────────────────────────────────────────────────────────────┘
                                                         │
                                                         v
                                                   ┌──────────┐
                                                   │ RECALLED │
                                                   └──────────┘

Status	Code	Description
Held	held	Ticket created for future course, not displayed yet
Pending	pending	Ticket sent to kitchen, waiting to start
In Progress	in_progress	Cook actively working on ticket
Ready	ready	Item(s) prepared, waiting for expo/pickup
Bumped	bumped	Ticket completed and cleared (terminal)
Recalled	recalled	Brought back after ready (for modifications)
Voided	voided	Ticket cancelled (terminal)

State Transition Rules

From State	Allowed Transitions
held	pending, voided
pending	in_progress, held, voided
in_progress	ready, pending, voided
ready	bumped, recalled, voided
recalled	in_progress, pending, voided
bumped	(terminal - no transitions)
voided	(terminal - no transitions)

---

Ticket Priority Levels

Priority	Code	Value	Description
Normal	normal	0	Standard order
High	high	1	VIP, rush order
Urgent	urgent	2	Remake, complaint resolution

---

Allergen Tracking

Tickets automatically include allergen information from menu items and modifiers:

{
  "items": [
    {
      "name": "Caesar Salad",
      "quantity": 1,
      "allergens": ["dairy", "gluten", "eggs"],
      "modifiers": [
        {
          "name": "Extra Parmesan",
          "allergens": ["dairy"]
        }
      ]
    }
  ]
}

Common Allergens

Allergen	Description
dairy	Milk, cheese, cream
gluten	Wheat, barley, rye
nuts	Tree nuts
peanuts	Peanuts
eggs	Eggs and egg products
soy	Soy and soy products
fish	Fish
shellfish	Shellfish, crustaceans
sesame	Sesame seeds

Allergens are fetched from the Menu Service during order routing and displayed prominently on tickets.

---

Display Settings

Station display settings are stored in the settings JSON field of the station object.

Recommended Settings Schema

{
  "columns": 3,
  "sort_by": "time",
  "show_modifiers": true,
  "show_server": true,
  "show_allergens": true,
  "alert_sound": true,
  "alert_threshold_seconds": 600,
  "color_coding": {
    "on_time": "#22c55e",
    "warning": "#f59e0b",
    "late": "#ef4444"
  }
}

Setting	Type	Description
columns	integer	Number of ticket columns (1-4)
sort_by	string	Sort order: time, priority
show_modifiers	boolean	Display item modifiers
show_server	boolean	Display server name
show_allergens	boolean	Display allergen banners
alert_sound	boolean	Play sound for new tickets
alert_threshold_seconds	integer	Time before "late" warning
color_coding	object	Hex colors for time-based styling

---

Error Responses

Station Not Found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Station not found"
  }
}

Insufficient Permissions (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "insufficient permissions to create stations"
  }
}

Invalid State Transition (400)

{
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "Cannot transition from bumped to in_progress"
  }
}

---

Sub-Pages

• Stations - Station management CRUD operations
• Tickets - Ticket lifecycle operations
• Routing - Routing rules and order routing
• Expo - Expo view and course firing
• Events - Real-time WebSocket events

---

Related Documentation

• Orders API - Order management
• Menu API - Menu item configuration
• WebSocket Events - Real-time updates
• KDS User Guide - Staff operations guide