Partially 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 partial-update-order command and supplying a payload of properties to update. A partial order update does not require all order properties to be included in the body request. This request should include only the properties that you wish to change. This may be helpful if your system operates on an eventual consistency model, where the order state may not be immediately synced between terminals. Using partial updates, you may rely on the KDS to manage the final order state.

Port	Protocol
9104	TCP

Body Parameters

Property	Required	Type	Description
command	yes	string	`partial-update-order`
order	yes	Partial KDS Order	object containing KDS order data

Partial KDS Order

Property	Required	Type	Description
id	yes	string	unique id of this KDS order. Must match the `id` from the original create request.
name	no	string	order/customer name
mode	no	string	accepted values: For Here, ToGo, Pickup, DriveThru, Delivery, Curbside
pickupTime	no	date	date/time for order pickup in ISO 8601 format
phoneNumber	no	string	customer phone number in E.164 format
server	no	string	name of employee creating the order
specialInstructions	no	string	special instructions for the order
vehicleModel	no	string	vehicle make and model
vehicleColor	no	string	vehicle color
priority	no	bool	if true order card will be flagged as priority and moved to front of queue
deliveryAddress	no	string	delivery address for order
deliveryService	no	DeliveryService	object with delivery service information
costs	no	Costs	object with order costs
originSource	no	string	third party order source
checkNumber	no	string	optional parameter that gets appended to the order name
deliveryHandoff	no	bool	if mode is Delivery and this is true the order will display as Delivery Handoff
prepTimeDuration	no	ISO 8601 string	time it takes to prepare order; example: PT30M; only applied if auto hold future orders is true
itemsToAdd	no	KdsItem[ ]	array of menu items to add to the order
itemsToUpdate	no	KdsItem[ ]	array of menu items to update on the order
itemsToRemove	no	string[ ]	array of `lineId`’s to remove from the order

The only required property is id
itemsToAdd: Uses the provided lineId on the Item to determine if this is a new Item on the order. Duplicate lineId’s will be ignored.
itemsToUpdate: Uses the provided lineId on the Item to determine which Items to update on the order. NonexistentlineId’s will be ignored.
itemsToRemove: Takes an array of lineId to determine which Items to remove from the order. Nonexistent lineId’s will be ignored.

Only include properties that should be updated. If a property is included on the request it will attempt to overwrite it on the order. Either send properties as null or do not include them in the body at all.

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

Update the order name and add an item to the order already on the KDS screen. Both of these requests are valid and yield the same result:

{
  "command": "partial-update-order",
  "order": {
    "id": "123",
    "name": "New order name",
    "mode": null,
    "pickupTime": null,
    "phoneNumber": null,
    "server": null,
    "specialInstructions": null,
    "vehicleModel": null,
    "vehicleColor": null,
    "priority": null,
    "deliveryAddress": null,
    "deliveryService": null,
    "costs": null,
    "originSource": null,
    "checkNumber": null,
    "deliveryHandoff": null,
    "prepTimeDuration": null,
    "itemsToAdd": [
      {
        "lineId": "3",
        "qty": 1,
        "name": "Hamburger",
        "mods": [
          "no tomato"
        ]
      }
    ],
    "itemsToUpdate": null,
    "itemsToRemove": null
  }
}

{
  "command": "partial-update-order",
  "order": {
    "id": "123",
    "name": "New order name",
    "itemsToAdd": [
      {
        "lineId": "3",
        "qty": 1,
        "name": "Hamburger",
        "mods": [
          "no tomato"
        ]
      }
    ]
  }
}

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

An updated order shows with an edited icon in the header
Added items appear with a + icon
Updated items appear with a edit icon
Removed items appear with a x icon and items are struckthrough

Partially Update KDS Orders Over Local Network