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

Retry

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

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.