KDS Orders
Routes
There are four routes available to get or post KDS order information. They are:
| Route | Description |
|---|---|
| GET KDS Active Orders | Returns all active orders on a specific screen |
| POST Create KDS Order | Create a KDS order to display on one or more screens |
| PUT Update KDS Order | Updates a KDS order on one or more screens |
| PUT Cancel KDS Order | Cancels a KDS order on one or more screens |
KDS Active Orders
Request
GET /integrators/kds-orders/active
Required Headers
x-integration-token: {token}
x-location-id: {locationId}
x-device-ids: {deviceId}
*For device ids you can pass a single device id, a list of device ids separated by commas, or ‘all’ to get information for all the location’s devices
Response
Fresh KDS will return information for all requested screens, including the total active order count per screen and an array of active orders. The orderId and orderName properties in the response correspond to the id and name values passed in when creating the order.
Example Response
[
{
"deviceId": "49d0d0a9-e7a8-438c-9e14-e26198e637df",
"deviceName": "Device 2",
"orderCount": 2,
"orders": [
{
"orderId": "223456789",
"orderName": "2 Test Order"
},
{
"orderId": "323456789",
"orderName": "2 Test Order 2"
}
]
},
{
"deviceId": "74b6041f-c095-47b9-ba4f-340b89142935",
"deviceName": "Device 3",
"orderCount": 1,
"orders": [
{
"orderId": "423456789",
"orderName": "3 Test Order"
}
]
}
]
Create KDS Order
Request
POST /integrators/kds-orders
Required Headers
x-integration-token: {token}
x-location-id: {locationId}
x-device-ids: {deviceId}
*For device ids you can pass a single device id, a list of device ids separated by commas, or ‘all’ to send the KDS order to all the location’s devices
Body Parameters
KDS Order
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | string | unique id of this KDS order |
| name | yes | string | order/customer name |
| time | yes | date | date/time order is placed in ISO 8601 format |
| pickupTime | no | date | date/time for order pickup in ISO 8601 format |
| phoneNumber | no | string | customer phone number in E.164 format |
| optInForSms | no | bool | if false KDS will not message customer for this order; default is true |
| deliveryAddress | no | string | delivery address for order |
| mode | yes | string | accepted values: For Here, ToGo, Pickup, DriveThru, Delivery, Curbside |
| deliveryHandoff | no | bool | if mode is Delivery and this is true the order will display as Delivery Handoff |
| server | no | string | name of employee creating the order |
| items | yes | KdsItem[] | array of menu items |
| terminal | no | string | POS terminal creating the order |
| specialInstructions | no | string | special instructions for the order |
| customerArrivedUrl | no | url | if present the URL will be added to the order received and order ready messages |
| vehicleModel | no | string | vehicle make and model |
| vehicleColor | no | string | vehicle color |
| costs | no | Costs | object with order costs |
| deliveryService | no | DeliveryService | object with delivery service information |
| originSource | no | string | third party order source; accepted values: UBEREATS, GRUBHUB, DOORDASH, OLO |
| retry | no | Retry | retry logic if screen is no connected when order is sent |
| checkNumber | no | string | optional parameter that gets appended to the order name |
| priority | no | bool | if true order card will be flagged as priority and moved to front of queue |
KDS Item
| Property | Required | Type | Description |
|---|---|---|---|
| id | no | string | id of item |
| lineId | no | string | must be unique within the order; used for processing order update command |
| name | yes | string | name of item |
| qty | yes | int | quantity of item |
| price | no | string | price of item; can include currency symbol |
| mods | yes | Modifier[] | array of item modifiers; send empty array for items without modifiers |
| specialInstructions | no | string | special instructions for item |
| course | no | string | course name/number of the item |
| courseStatus | no | string | valid values are “straightFire”, “hold”, “fire”, and “pickup” |
| seat | no | string | seat number of the item |
Modifier
| Property | Required | Type | Description |
|---|---|---|---|
| id | no | string | id of modifier |
| name | yes | string | name of modifier |
previously item.mods was a string[], which is still supported for backwards compatibility
Costs
| Property | Required | Type | Description |
|---|---|---|---|
| subtotal | no | string | subtotal of order |
| tax | no | string | tax on order |
| deliveryFee | no | string | delivery fee on order |
| surcharge | no | string | surcharge on order |
| convenienceFee | no | string | convenience fee on order |
| tip | no | string | tip on order |
| additionalFees | no | additionalFees[] | array of additional fees |
| total | no | string | total of order |
| promoCodes | no | promoCodes[] | array of promo codes on order |
all properties in the Costs object are strings and can include currency symbols for display
Additional Fees
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | name of fee |
| amount | yes | string | amount of fee; can include currency symbol |
Promo Codes
| Property | Required | Type | Description |
|---|---|---|---|
| name | no | string | name of promo code |
| amount | yes | string | amount of promo; can include currency symbol |
Delivery Service
| Property | Required | Type | Description |
|---|---|---|---|
| name | yes | string | name of delivery service |
| orderId | yes | string | delivery service order ID |
| driverPhone | no | string | delivery driver phone number in E.164 format |
Retry
| Property | Required | Type | Description |
|---|---|---|---|
| notificationUrl | no | string | URL to POST final success or failure to |
| expiration | no | date | timestamp of when retries should cease in ISO 8601 format; default is 2 minutes after submission time |
Example
{
"id": "123",
"name": "John Doe",
"time": "2023-04-03T13:48:38.769Z",
"pickupTime": "2023-04-03T14:15:00.000Z",
"phoneNumber": "+16155551234",
"mode": "Pickup",
"items": [{
"lineId": "1",
"name": "Hamburger",
"qty": 1,
"mods": ["No Ketchup", "Side Fries"],
"course": "Course 1",
"seat": "Seat 1",
"courseStatus": "fire"
},
{
"lineId": "2",
"name": "Vanilla Shake",
"qty": 1,
"mods": [],
"course": "Course 2",
"seat": "Seat 1",
"courseStatus": "hold"
}
]
}
Examples of Object Mapping to KDS Screens
KDS Order
Take Out Order - Delivery
Take Out Order - Curbside
Responses
Success Response Example
{
"orderId" : "123",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
the orderId value in the response will match the id provided in the request payload
Update KDS Order
Request
PUT /integrators/kds-orders
Required Headers
x-integration-token: {token}
x-location-id: {locationId}
x-device-ids: {deviceId}
*For device ids you can pass a single device id, a list of device ids separated by commas, or ‘all’ to update the KDS order on all the location’s devices
Body Parameters
The body parameters for the request are identical to the Create KDS Order request. The id provided in the update request must match the id from the original create request. Non-matching id values will be ignored.
The update request must include all the properties for the KDS order, even if there has been no change.
To apply changes to the KDS items array you must provide the same lineId values as the original request. Items on the KDS order that are no longer present in the update request will be removed from the KDS order and flagged as “deleted” on the screen.
Responses
Success Response Example
{
"orderId" : "123",
"deliveryStatuses": [
{
"device": "e1675528-aba9-4b97-8482-a72380870fd5",
"status": "success"
}
]
}
Cancel KDS Order
Request
PUT /integrators/kds-orders/cancel
Required Headers
x-integration-token: {token}
x-location-id: {locationId}
x-device-ids: {deviceId}
*For device ids you can pass a single device id, a list of device ids separated by commas, or ‘all’ to cancel the KDS order on all the location’s devices
Body Parameters
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | string | id of the KDS order to cancel |
Non-matching id values will be ignored. When a KDS order is successfully canceled the appearance on the KDS screen will change to include a red banner to indicate the canceled status.