KDS (Kitchen Display System)

KDS requests allow you to manage Kitchen Display System operations, including retrieving pending and completed orders, monitoring order status changes, and updating order states in real-time.

1 - Get KDS Order List

"Retrieve the list of orders from a specific KDS folder (PENDING or COMPLETED)."

Request

Definitions Example 

{
    "requestType": String,
    "actionType": String,
    "folder": String,
    "printerID": Number
}
            

{
    "requestType": "kds",
    "actionType": "getList",
    "folder": "PENDING",
    "printerID": 1
}

See definitions

Response

Definitions Example 

{
    "status": String,
    "kdsBoxList": [{
        "id": String,
        "printerID": Number,
        "list": Array,
        "ticketData": Object,
        "terminal_number": String,
        "user_id": String,
        "user_name": String,
        "created": Number,
        "created_human": String,
        "modified": Number,
        "modified_human": String
    }]
}
            

{
    "status": "OK",
    "kdsBoxList": [{
        "id": "11751233353162",
        "printerID": 3,
        "list": [{
            "item": {
                "menu_id": "1527077721022",
                "qty": 1,
                "name": "Stack",
                "price": 1000,
                "modifier": {...}
            },
            "qty": -1
        }],
        "ticketData": {
            "tax": 110,
            "subtotal": 1040,
            "total": 1337,
            "number": 1002,
            "table_number": 7,
            "table_name": "A1",
            "list_item": [...]
        },
        "terminal_number": "1",
        "user_id": "1",
        "user_name": "GM3",
        "created": 1751233359,
        "created_human": "06/29/2025 05:42:39 PM",
        "modified": 1751233359,
        "modified_human": "06/29/2025 05:42:39 PM"
    }]
}

See definitions

2 - Get Folder Signature

"Retrieve a timestamp signature for a KDS folder to detect changes without fetching the entire list."

Request

Definitions Example 

{
    "requestType": String,
    "actionType": String,
    "folder": String
}
            

{
    "requestType": "kds",
    "actionType": "getFolderSignature",
    "folder": "PENDING"
}

See definitions

Response

Definitions Example 

{
    "status": String,
    "signature": Number
}
            

{
    "status": "OK",
    "signature": 1720632049
}

See definitions

3 - Save KDS Box

"Update a KDS order box status or move it between folders (e.g., from PENDING to COMPLETED)."

Request

Definitions Example 

{
    "requestType": String,
    "actionType": String,
    "folder": String,
    "kdsBoxData": {
        "id": String,
        "printerID": Number,
        "list": Array,
        "ticketData": Object,
        "terminal_number": String,
        "user_id": String,
        "user_name": String,
        "created": Number,
        "created_human": String,
        "modified": Number,
        "modified_human": String
    }
}
            

{
    "requestType": "kds",
    "actionType": "save",
    "folder": "COMPLETED",
    "kdsBoxData": {
        "id": "11751233353162",
        "printerID": 3,
        "list": [{
            "item": {
                "menu_id": "1527077721022",
                "qty": 1,
                "name": "Stack",
                "price": 1000
            },
            "qty": -1
        }],
        "ticketData": {
            "tax": 110,
            "subtotal": 1040,
            "total": 1337,
            "number": 1002,
            "table_number": 7
        },
        "terminal_number": "1",
        "user_id": "1",
        "user_name": "GM3",
        "created": 1751233359,
        "created_human": "06/29/2025 05:42:39 PM",
        "modified": 1751233359,
        "modified_human": "06/29/2025 05:42:39 PM"
    }
}

See definitions

Response

Definitions Example 

{
    "status": String
}
            

{
    "status": "OK"
}

See definitions

Definitions

Request Definitions

Definition Type Description
actionType String (["getList", "getFolderSignature", "save"]) Unique action identifier for your request.
folder String (["PENDING", "COMPLETED"]) The KDS folder to operate on. PENDING contains active orders, COMPLETED contains finished orders.
printerID Number (optional) Filter results by a specific kitchen printer/station ID. When omitted, returns orders for all printers.
kdsBoxData Object KDS order box data containing the complete order information including void items, ticket data, and metadata.
kdsBoxData.id String (required) Unique identifier for the KDS order box (e.g., timestamp-based ID).
kdsBoxData.printerID Number (required) The numeric printer/station ID this order is assigned to.
kdsBoxData.list Array Array of order item modifications (voids, changes) with item details and quantity adjustments.
kdsBoxData.ticketData Object Complete ticket/order information including totals, items, table info, customer details, and timestamps.
kdsBoxData.terminal_number String The terminal number where the order was created.
kdsBoxData.user_id String User ID of the person who created/modified the order.
kdsBoxData.user_name String User name of the person who created/modified the order.
kdsBoxData.created Number (timestamp) Unix timestamp when the KDS box was created.
kdsBoxData.created_human String Human-readable creation date and time.
kdsBoxData.modified Number (timestamp) Unix timestamp when the KDS box was last modified.
kdsBoxData.modified_human String Human-readable last modified date and time.

Response Definitions

Definition Type Description
status String Request status.
kdsBoxList Object[] Array of KDS order boxes with their details and current status.
signature Number Timestamp indicating the last modification time of the folder. Use this to detect changes efficiently.

Usage Notes

  • When saving a KDS box to a new folder, the system automatically removes it from the opposite folder
  • Use getFolderSignature for efficient polling - only fetch the full list when the signature changes
  • The printerID filter in getList allows you to show orders specific to each kitchen station