KDS Orders

Routes

There are four routes available to get or post KDS order information. They are:

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

KDS Item

Modifier

previously item.mods was a string[], which is still supported for backwards compatibility

Costs

all properties in the Costs object are strings and can include currency symbols for display

Additional Fees

Promo Codes

Delivery Service

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

HTTP Response Code: 201 - Created

{
    "orderId" : "123",
    "deliveryStatuses": [
        {
            "device": "e1675528-aba9-4b97-8482-a72380870fd5",
            "status": "success",
            "type": "android
        }
    ]
}

the orderId value in the response will match the id provided in the request payload

Resource Already Exists Response Example

HTTP Response Code: 409 - Conflict

{
	"message": "Could not create resource. Id already exists"
}

you will get this response if the id already exsits for an order at the location

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

HTTP Response Code: 200 - OK

{
    "orderId" : "123",
    "deliveryStatuses": [
        {
            "device": "e1675528-aba9-4b97-8482-a72380870fd5",
            "status": "success"
        }
    ]
}

Resource Not Found Response Example

HTTP Response Code: 404 - Not Found

{
	"message": "Could not update. No resource found"
}

you will get this response if the id does not exsit for an order at the location

Partial Update KDS Order

Request

PUT /integrators/kds-orders/partial

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

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.

Partial KDS 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. Include all item properties when updating - partial item updates are not supported.
• itemsToRemove: Takes an array of lineId to determine which Items to remove from the order. Nonexistent lineId’s will be ignored.

Only include order 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.

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:

{
  "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,
  "covers": null,
  "itemsToAdd": [
      {
          "lineId": "3",
          "qty": 1,
          "name": "Hamburger",
          "mods": [
              "no tomato"
          ]
      }
  ],
  "itemsToUpdate": null,
  "itemsToRemove": null
}

OR

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

Responses

Same responses as Update KDS Order Responses

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

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.