Update KDS Order Over Local Network
Overview
After sending a KDS order to a screen you can update the content of the order using the update-order command and supplying the updated order payload. You will need to re-send the entier order payload, including fields that have not changed.
The lineId property is used to add, update, or delete menu items. To delete menu items from an order remove the item’s lineId from the items array. To add menu items to an order add an additional item with a new lineId to the items array.
Body Parameters
| Property |
Required |
Type |
Description |
| command |
yes |
string |
accepted values: create-order, update-order, cancel-order |
| order |
yes |
Order |
object containing KDS order data |
command property added in version 2.21.30, for backwards compatibility default value is create-order
Order
| Property |
Required |
Type |
Description |
| id |
yes |
string |
unique id of the KDS order to update |
| name |
yes |
string |
order/customer name |
| time |
yes |
int |
milliseconds since epoch |
| 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 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 |
| 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 |
| 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 |
Example
{
"command": "update-order",
"order": {
"id": "123",
"name": "Jane Doe",
"time": 1551454803184,
"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 2",
"seat": "Seat 1",
"courseStatus": "fire"
},
{
"lineId": "2",
"name": "Chocolate Shake",
"qty": 1,
"mods": [],
"course": "Course 3",
"seat": "Seat 1",
"courseStatus": "hold"
},
{
"lineId": "3",
"name": "Onion Rings",
"qty": 1,
"mods": ["BBQ Sauce"],
"course": "Course 1",
"seat": "For Table",
"courseStatus": "fire"
}
]
}
}
Responses
| Response Type |
Response Value |
| Success |
order.id value |
| Failure |
Unable to parse data |
| Failure |
ORDER_DOES_NOT_EXIST - The order.id sent in the update request does not exist on the device |
Screen Behavior
- if the KDS order has already been bumped from the screen the
update-order command will be ignored
- if completed items on the KDS order are edited or deleted the completed state will be removed and replaced with the edited or deleted state