KDS (Kitchen Display System)

Overview

The Kitchen Display System (KDS) shows incoming orders to kitchen staff. Orders appear on screen with item details, modifiers, and timing information.

Key Purpose: Display orders to kitchen staff for preparation.

Purpose

This page lets you set up and manage Kitchen Display System stations that show incoming orders to kitchen staff, enabling them to track, prioritize, and mark items as complete.

Key Concepts

KDS Station: A display device (tablet or screen) registered to a location that shows orders filtered by category and channel; each station requires an active Stripe subscription.
Order Status Flow: Orders on the KDS follow a strict sequence -- Queued, In Progress, Ready, Complete -- and each transition is enforced by the backend (e.g., only a Queued order can move to In Progress).
Optimistic Locking: Concurrent updates to the same order or item are prevented using a 10-second database lock; a 409 conflict error is returned if another user is already modifying the same record.
Bump: The action of marking an individual item or an entire order as done; bumping an order to Complete also automatically marks all remaining items as done and closes any linked QR table ordering session.
Priority and Hold: Orders can be flagged as priority (moved up in importance) or placed on hold (deprioritized), giving kitchen staff flexibility in preparation sequencing.

Actions

Mark Order In Progress

Move a queued order to "In Progress" status, signaling that kitchen staff have started preparation.

Mark Order Ready

Advance an in-progress order to "Ready" status, indicating all items are prepared and the order is awaiting pickup or delivery.

Mark Order Complete

Finalize a ready order as "Complete," which auto-marks all remaining items as done and closes any associated QR table ordering session.

Prioritize or Hold an Order

Flag an order as high priority to move it up in the queue, or place it on hold to temporarily deprioritize it.

Update KDS Settings

Configure station-level filter categories, display preferences, and alert settings directly from the KDS device.

Location

Backoffice Route: /devices/kds
Backend Controller: app/Http/Controllers/Api/KdsController.php
KDS App: Flutter application (mobile/desktop)

Concepts

KDS Station

A display showing orders for a specific prep area.

Order Ticket

Visual representation of an order on the KDS.

Bump

Action to mark an order/item as complete.

Routing

Directing orders to specific stations based on items.

KDS Device Fields

Station Name

Property	Value
Field ID	`name`
Label	Station Name
Type	Text
Required	Yes
Validation	max: 50 characters

Description: Name for this KDS station.

Examples:

"Grill Station"
"Fryer"
"Drinks"
"Expo"
"Main Kitchen"

Assigned Location

Property	Value
Field ID	`location_id`
Label	Location
Type	Select
Required	Yes

Description: Which location this KDS belongs to.

Station Type

Property	Value
Field ID	`station_type`
Label	Station Type
Type	Select
Options	prep, expo, all
Default	all

Description: Type of station determines what orders it shows.

Types:

Prep: Shows items for preparation
Expo: Shows complete orders for assembly/dispatch
All: Shows all orders

Assigned Categories

Property	Value
Field ID	`category_ids`
Label	Categories
Type	Multi-select
Required	No
Default	All categories

Description: Which menu categories this station handles.

Business Logic:

Only items from selected categories shown
Empty = all categories

Examples:

Grill Station: Burgers, Steaks
Fryer: Fries, Chicken
Drinks: Beverages, Shakes

Order Channels

Property	Value
Field ID	`channels`
Label	Order Channels
Type	Multi-select
Options	online_ordering, kiosk, in_house, third_party
Default	All

Description: Which order channels to display.

Examples:

All channels on main KDS
Separate KDS for delivery orders only

Display Mode

Property	Value
Field ID	`display_mode`
Label	Display Mode
Type	Select
Options	tickets, list, grid
Default	tickets

Description: How orders are displayed.

Modes:

Tickets: Traditional ticket view (columns)
List: Vertical list of orders
Grid: Grid layout

Auto-Bump Timer

Property	Value
Field ID	`auto_bump_minutes`
Label	Auto-Bump After
Type	Number
Unit	Minutes
Default	null (disabled)
Validation	min: 1

Description: Automatically bump orders after X minutes.

Use Cases:

Prevent old orders from clogging screen
Automatic completion for simple items

Sound Alerts

Property	Value
Field ID	`sound_enabled`
Label	Sound Alerts
Type	Toggle
Default	true

Description: Play sound when new orders arrive.

Alert Sound

Property	Value
Field ID	`alert_sound`
Label	Alert Sound
Type	Select
Options	chime, bell, beep, custom
Default	chime

Description: Sound played for new orders.

Color Coding

Property	Value
Field ID	`color_coding`
Label	Time-Based Colors
Type	Toggle
Default	true

Description: Change ticket color based on wait time.

Colors:

Green: New order (0-5 min)
Yellow: Getting old (5-10 min)
Red: Urgent (10+ min)

Time Thresholds

Property	Value
Field ID	`time_thresholds`
Label	Color Thresholds
Type	Object
Default

Description: Minutes before color changes.

Order Ticket Display

Ticket Information

Each order ticket shows:

Order Number: #42
Order Time: When order was placed
Wait Time: How long since order placed
Channel: Online, Kiosk, etc.
Dining Option: Pickup, Delivery, Dine-in
Customer Name: If available
Items: List of items with modifiers
Special Instructions: Notes from customer

Item Display

Each item shows:

Quantity: 2x
Item Name: Cheeseburger
Modifiers:
- Size: Large
- Extra Cheese
- No Pickles
Notes: "Extra crispy"

Business Logic

Order Routing

New order received
        │
        ▼
For each KDS station:
├── Check location match
├── Check channel filter
├── Check category filter
│
└── If matches → Send to station

Order Flow on KDS

Order appears on KDS
        │
        ▼
Staff prepares items
        │
        ▼
Staff bumps individual items (optional)
        │
        ▼
Staff bumps entire order
        │
        ▼
Order moves to Expo (if configured)
        │
        ▼
Order marked as ready
        │
        ▼
Customer notified (if applicable)

Multi-Station Workflow

Order: Burger + Fries + Drink

Grill Station (Burgers):
- Shows: Burger
- Bumps when burger ready

Fryer Station (Fries):
- Shows: Fries
- Bumps when fries ready

Drinks Station:
- Shows: Drink
- Bumps when drink ready

Expo Station:
- Shows: Full order
- Waits for all items bumped
- Assembles and dispatches

Recall Function

Order bumped by mistake
        │
        ▼
Staff uses "Recall" function
        │
        ▼
Order reappears on KDS
        │
        ▼
Can be bumped again when ready

Customer Impact

KDS doesn't directly face customers, but affects:

Order Timing

Efficient KDS workflow = faster orders
Color coding helps prioritize

Order Accuracy

Clear modifier display = correct orders
Special instructions visible

Notifications

When order bumped → Customer can be notified
"Your order is ready!"

Relations

Depends On

Locations: KDS per location
Categories: For routing
Transactions: Orders displayed

Affects

Order Status: Updated when bumped
Customer Notifications: Triggered on ready
Reports: Prep time analytics

Business Rules

Order status transitions are strictly enforced: Queued to In Progress, In Progress to Ready, Ready to Complete; skipping a step returns a 400 error.
The KDS only displays orders whose payment status is Complete and whose order status is not yet Complete, with an order date no more than one hour in the future.
Each item and order modification acquires a 10-second optimistic lock; if a second user attempts to modify the same record simultaneously, a 409 Conflict error is returned.
When an order is marked Complete, all transaction items that are not already marked as done are bulk-updated to done in a single operation.
Completing an order also triggers automatic closure of any linked QR table ordering session via the TableQrOrderingService.

FAQs

"Why can I not mark an order as Ready?" The order must be in "In Progress" status first; the backend enforces the Queued to In Progress to Ready to Complete sequence and rejects out-of-order transitions.
"What happens if two staff members bump the same item at the same time?" The system uses optimistic locking with a 10-second window; the first action succeeds and the second receives a 409 Conflict error, preventing data corruption.
"Can I undo a bump?" Yes, the KDS supports a recall function that sets an item's is_done flag back to false, causing the order to reappear on the display.
"How does category filtering work on a KDS station?" Each station stores a filter with selected category IDs; only order items belonging to those categories are shown, allowing dedicated stations (e.g., Grill, Drinks) to see only relevant items.
"Does marking an order complete notify the customer?" Yes, completing an order triggers a PushOrderEvent that can be used downstream to send customer notifications such as "Your order is ready."

Troubleshooting

Problem: Orders not appearing on KDS

Causes:

KDS not connected
Wrong location assigned
Category filter excluding items
Channel filter excluding orders

Solutions:

Check KDS connection status
Verify location assignment
Review category filters
Check channel settings

Problem: Orders appearing on wrong station

Causes:

Category routing incorrect
Multiple stations with same categories
"All" station catching everything

Solutions:

Review category assignments
Make categories exclusive to stations
Configure station types properly

Problem: No sound alerts

Causes:

Sound disabled in settings
Device volume muted
Browser/app permissions

Solutions:

Enable sound in KDS settings
Check device volume
Grant audio permissions

Problem: Orders stuck on screen

Causes:

Staff not bumping orders
Auto-bump not configured
App frozen

Solutions:

Train staff on bumping
Configure auto-bump timer
Restart KDS app

Problem: Color coding not working

Causes:

Color coding disabled
Thresholds set too high
Time sync issue

Solutions:

Enable color coding
Adjust time thresholds
Check device time settings

Examples

Single Station (Small Kitchen)

json

{
  "station": {
    "name": "Kitchen",
    "location_id": "loc-123",
    "station_type": "all",
    "category_ids": [],
    "channels": ["online_ordering", "kiosk", "in_house"],
    "display_mode": "tickets",
    "sound_enabled": true,
    "color_coding": true,
    "time_thresholds": {
      "yellow": 5,
      "red": 10
    }
  }
}

Multi-Station Setup

json

{
  "stations": [
    {
      "name": "Grill",
      "station_type": "prep",
      "category_ids": ["burgers", "steaks", "chicken"],
      "display_mode": "tickets"
    },
    {
      "name": "Fryer",
      "station_type": "prep",
      "category_ids": ["fries", "appetizers"],
      "display_mode": "tickets"
    },
    {
      "name": "Drinks",
      "station_type": "prep",
      "category_ids": ["beverages", "shakes"],
      "display_mode": "list"
    },
    {
      "name": "Expo",
      "station_type": "expo",
      "category_ids": [],
      "display_mode": "tickets"
    }
  ]
}

Delivery-Only Station

json

{
  "station": {
    "name": "Delivery Orders",
    "station_type": "all",
    "channels": ["online_ordering"],
    "display_mode": "list",
    "sound_enabled": true,
    "alert_sound": "bell"
  }
}

Fast Food (Quick Bump)

json

{
  "station": {
    "name": "Main Kitchen",
    "station_type": "all",
    "display_mode": "grid",
    "auto_bump_minutes": 15,
    "color_coding": true,
    "time_thresholds": {
      "yellow": 3,
      "red": 5
    }
  }
}

KDS Best Practices

Station Organization

Separate stations by prep area
Use Expo station for order assembly
Keep category assignments exclusive

Display Settings

Enable color coding for urgency
Set appropriate time thresholds
Use sound alerts for new orders

Workflow

Train staff on bump procedure
Use recall for mistakes
Monitor average prep times

Hardware

Use dedicated tablets/screens
Mount at eye level
Ensure good lighting
Keep screens clean

KDS (Kitchen Display System) ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Mark Order In Progress ​

Mark Order Ready ​

Mark Order Complete ​

Prioritize or Hold an Order ​

Update KDS Settings ​

Location ​

Concepts ​

KDS Station ​

Order Ticket ​

Bump ​

Routing ​

KDS Device Fields ​

Station Name ​

Assigned Location ​

Station Type ​

Assigned Categories ​

Order Channels ​

Display Mode ​

Auto-Bump Timer ​

Sound Alerts ​

Alert Sound ​

Color Coding ​

Time Thresholds ​

Order Ticket Display ​

Ticket Information ​

Item Display ​

Business Logic ​

Order Routing ​

Order Flow on KDS ​

Multi-Station Workflow ​

Recall Function ​

Customer Impact ​

Order Timing ​

Order Accuracy ​

Notifications ​

Relations ​

Depends On ​

Affects ​

Related Features ​

Business Rules ​

FAQs ​

Troubleshooting ​

Problem: Orders not appearing on KDS ​

Problem: Orders appearing on wrong station ​

Problem: No sound alerts ​

Problem: Orders stuck on screen ​

Problem: Color coding not working ​

Examples ​

Single Station (Small Kitchen) ​

Multi-Station Setup ​

Delivery-Only Station ​

Fast Food (Quick Bump) ​

KDS Best Practices ​

Station Organization ​

Display Settings ​

Workflow ​

Hardware ​

KDS (Kitchen Display System)

Overview

Purpose

Key Concepts

Actions

Mark Order In Progress

Mark Order Ready

Mark Order Complete

Prioritize or Hold an Order

Update KDS Settings

Location

Concepts

KDS Station

Order Ticket

Bump

Routing

KDS Device Fields

Station Name

Assigned Location

Station Type

Assigned Categories

Order Channels

Display Mode

Auto-Bump Timer

Sound Alerts

Alert Sound

Color Coding

Time Thresholds

Order Ticket Display

Ticket Information

Item Display

Business Logic

Order Routing

Order Flow on KDS

Multi-Station Workflow

Recall Function

Customer Impact

Order Timing

Order Accuracy

Notifications

Relations

Depends On

Affects

Related Features

Business Rules

FAQs

Troubleshooting

Problem: Orders not appearing on KDS

Problem: Orders appearing on wrong station

Problem: No sound alerts

Problem: Orders stuck on screen

Problem: Color coding not working

Examples

Single Station (Small Kitchen)

Multi-Station Setup

Delivery-Only Station

Fast Food (Quick Bump)

KDS Best Practices

Station Organization

Display Settings

Workflow

Hardware