# Kitchen Ticket Status

Read the preparation status of orders on the Kitchen Display System (KDS): accepted, in preparation, ready, picked up or cancelled. Each order sent to the kitchen display gets a ticket, identified by the `orderId` returned when the order is created (see [Create Orders](https://developers.innovorder.io/docs/orders/orders-create.md)), sent as a string.

These endpoints are served by the kitchen service, on its own host. They take the same `Authorization: Bearer <token>` header as the rest of the API (see [Authentication](https://developers.innovorder.io/docs/authentication/authentication.md)), for a Brand, Brand Group or Restaurant user with access to the restaurant.

**Base URLs**

```text
Production:     https://kitchen-backend-prod.innovorder.io
Preproduction:  https://kitchen-backend-preprod.innovorder.io
```

#### Polling

-   No event is sent when a ticket status changes: the [order webhooks](https://developers.innovorder.io/docs/webhooks/webhooks-orders.md) only cover payment and cancellation. Poll these endpoints instead.
-   Call them from your server, never from customer devices: the token grants access to the restaurant.
-   Group the orders in progress of a restaurant in one call with `orderIds[]`, and make at most one call every 10 seconds per restaurant.
-   Stop polling an order once its ticket reaches DONE or CANCELLED.
-   An order has no ticket before it reaches the kitchen display, and its ticket is deleted 20 hours after the order expected time. In both cases the order is missing from the list, and the single-ticket endpoint returns 404.

#### Ticket Statuses

The statuses a ticket goes through depend on how the restaurant kitchen display is set up: waiting mode, and customer pickup screen with or without automatic display.

WAITING

The kitchen display received the ticket and holds it until the kitchen starts it. Only used when the waiting mode is enabled on the restaurant kitchen display; otherwise the ticket goes straight to TO\_DO.

TO\_DO

The ticket is on the kitchen preparation screen. A scheduled order stays in the "Upcoming" column until its preparation time.

MODIFIED

The order was modified after it reached the kitchen. The kitchen has to acknowledge the change, then the ticket goes back to TO\_DO.

TO\_DISPLAY

Preparation is finished and the order waits to be called on the customer pickup screen (pickup screen enabled, without automatic display).

DISPLAYING

The order is called on the customer pickup screen: it is ready to be picked up.

DONE

Final status. Without a pickup screen: preparation is finished. With a pickup screen: the order was removed from the screen, i.e. handed over to the customer.

TO\_CANCEL

The cancellation reached the kitchen display and waits for the kitchen to acknowledge it.

CANCELLED

Final status. The kitchen acknowledged the cancellation.

### `GET /v1/restaurants/{restaurantId}/tickets` - List Kitchen Tickets

Retrieve the kitchen tickets of several orders of a restaurant. Pass either orderIds\[\] or groupingKey. Orders without a ticket are left out of the list. Returns 400 when neither is given.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer | Yes | The unique identifier of the restaurant. |
| orderIds\[\] | array | No | Query parameter. Order identifiers, repeated with brackets, even for a single order: ?orderIds\[\]=1927060&orderIds\[\]=1927061. Required unless groupingKey is given. |
| groupingKey | string | No | Query parameter. Returns the tickets that share this grouping key instead (see groupingKey in the response). |

#### Response

```json
{
  "status": 200,
  "code": "OK",
  "message": "Success",
  "data": [
    {
      "orderId": "1927060",
      "ticketNumber": "42",
      "status": "TO_DO"
    },
    {
      "orderId": "1927061",
      "ticketNumber": "43",
      "status": "DISPLAYING"
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| status | integer | Not specified | 200 | HTTP status code returned by the API. |
| code | string | Not specified | "OK" | Machine-readable application code for the result. |
| message | string | Not specified | "Success" | Human-readable result message. Do not use this value for program logic. |
| data | array | Not specified | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | Not specified | {…} | Endpoint-specific response payload. |
| data\[\].orderId | string | Yes | "1927060" | Identifier of the order. |
| data\[\].ticketNumber | string | Yes | "42" | Ticket number shown in the kitchen and on the pickup screen. |
| data\[\].status | string | Yes | "TO\_DO" | Ticket status, see Ticket Statuses above. |
| data\[\].groupingKey | string | No | Not provided | Only on sit-in tickets when the kitchen display groups tickets by table: the table name and a daily counter (for example "12-3"). Omitted otherwise. |

### `GET /v1/restaurants/{restaurantId}/tickets/{orderId}` - Get Kitchen Ticket

Retrieve the kitchen ticket of one order. Returns 404 when the order has no ticket: not yet sent to the kitchen display, or deleted 20 hours after the order expected time.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| restaurantId | integer | Yes | The unique identifier of the restaurant. |
| orderId | string | Yes | The identifier of the order, as returned when the order is created. |

#### Response

```json
{
  "status": 200,
  "code": "OK",
  "message": "Success",
  "data": {
    "orderId": "1927060",
    "ticketNumber": "42",
    "status": "TO_DO"
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| status | integer | Not specified | 200 | HTTP status code returned by the API. |
| code | string | Not specified | "OK" | Machine-readable application code for the result. |
| message | string | Not specified | "Success" | Human-readable result message. Do not use this value for program logic. |
| data | object | Not specified | {…} | Endpoint-specific response payload. |
| data.orderId | string | Yes | "1927060" | Identifier of the order. |
| data.ticketNumber | string | Yes | "42" | Ticket number shown in the kitchen and on the pickup screen. |
| data.status | string | Yes | "TO\_DO" | Ticket status, see Ticket Statuses above. |
| data.groupingKey | string | No | Not provided | Only on sit-in tickets when the kitchen display groups tickets by table. Omitted otherwise. |

**404 Not Found**

```json
{
  "status": 404,
  "code": "Not Found",
  "message": "Ticket not found"
}
```