# Get orders!

ℹ️ OctoTable enables the creation of digital menus for takeaway, delivery, or table orders. Through the API, you can directly retrieve orders and the individual items selected by customers

⚙️ **Use the base resource URL** for the following examples, or [see the complete collection](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#6b481505-7c08-4328-a3da-c11bfb5aa156)

```
https://api.octorate.com/octotable-pms/api/v2
```

## 🔍 Find all orders

<mark style="color:green;">**`GET`**</mark> `/orders`

Retrieves a list of all orders for the specified property (e.g., restaurant) using the property ID [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#99cd5dc5-dec9-41c7-be88-52ee36c46cbe)

**Headers**

<table><thead><tr><th width="345">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td><code>application/json</code></td></tr><tr><td><code>Authorization</code></td><td><code>Bearer &#x3C;token></code></td></tr><tr><td><code>Property</code></td><td><code>&#x3C;your_property_id></code></td></tr></tbody></table>

**Query params**

<table><thead><tr><th width="345">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>start_date</code></td><td>date time</td><td>Start day of search</td></tr><tr><td>end_date</td><td>date time</td><td>End day of search</td></tr><tr><td><code>status[]</code></td><td>[UNREAD, WAITING, PREPARING, READY, DELIVERED]</td><td>The list of order status</td></tr><tr><td>delivery_mode</td><td>[ROOM,TAKEAWAY,DELIVERY,]</td><td>The delivery mode</td></tr><tr><td><code>service_ids[]</code></td><td>[int]</td><td>The id list of services</td></tr><tr><td><code>room_ids[]</code></td><td>[int]</td><td>The id list of rooms</td></tr><tr><td>text_search</td><td>text</td><td>A generic text to search in orders</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200 OK" %}

```
{
  "data": [
    {
      "channel": "OCTOTABLE_BOOK",
      "create_time": "2025-07-24T17:20:26",
      "customer": {
        "id": 34112273,
        "first_name": "Elsie",
        "last_name": "Dillon",
        "email": "howe.weeks@gmail.nexus",
        "phone": "+443125450222"
      },
      "id": 33319904,
      "mode": "ROOM",
      "order": [
        {
          "id": 451917,
          "reservation": 33319904,
          "insert_date": "2025-07-25T15:48:54",
          "status": "UNREAD",
          "article": {
            "id": 313080,
            "name": "Sandwich",
            "price": 3,
            "image": "1000173/1753370761583.jpg",
            "allergens": [],
            "category_id": 65614,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {},
            "variations": []
          },
          "currency": "EUR",
          "quantity": 1,
          "total": 3
        },
        {
          "id": 451919,
          "reservation": 33319904,
          "insert_date": "2025-07-25T15:58:49",
          "status": "UNREAD",
          "article": {
            "id": 313078,
            "name": "Pizza",
            "price": 10,
            "image": "1000173/1753370698219.jpg",
            "allergens": [],
            "category_id": 65614,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {},
            "variations": []
          },
          "currency": "EUR",
          "quantity": 2,
          "total": 20
        }
      ],
      "order_cost": 23,
      "room": {
        "id": 23694,
        "name": "Garden",
        "tables": [
          {
            "id": 204838,
            "name": "1",
            "online": true,
            "out_of_order": false
          }
        ]
      },
      "service": {
        "id": 34567,
        "name": "Dinner",
        "card_guarantee": false
      },
      "start_date": "2025-07-25T19:00:00",
      "total_cost": 23,
      "total_paid": 0
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🔍 Find orders by reservation ID

<mark style="color:green;">**`GET`**</mark> `/reservations/{reservation_id}`

Retrieves an order by the reservation ID [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#48571ecb-91b6-4158-acdf-811082d0713b)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Response**

{% tabs %}
{% tab title="200 OK" %}

```
{
  "data": [
    {
      "channel": "OCTOTABLE_BOOK",
      "create_time": "2025-07-24T17:20:26",
      "customer": {
        "id": 34112273,
        "first_name": "Elsie",
        "last_name": "Dillon",
        "email": "howe.weeks@gmail.nexus",
        "phone": "+443125450222"
      },
      "id": 33319904,
      "mode": "ROOM",
      "order": [
        {
          "id": 451917,
          "reservation": 33319904,
          "insert_date": "2025-07-25T15:48:54",
          "status": "UNREAD",
          "article": {
            "id": 313080,
            "name": "Sandwich",
            "price": 3,
            "image": "1000173/1753370761583.jpg",
            "allergens": [],
            "category_id": 65614,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {},
            "variations": []
          },
          "currency": "EUR",
          "quantity": 1,
          "total": 3
        },
        {
          "id": 451919,
          "reservation": 33319904,
          "insert_date": "2025-07-25T15:58:49",
          "status": "UNREAD",
          "article": {
            "id": 313078,
            "name": "Pizza",
            "price": 10,
            "image": "1000173/1753370698219.jpg",
            "allergens": [],
            "category_id": 65614,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {},
            "variations": []
          },
          "currency": "EUR",
          "quantity": 2,
          "total": 20
        }
      ],
      "order_cost": 23,
      "room": {
        "id": 23694,
        "name": "Garden",
        "tables": [
          {
            "id": 204838,
            "name": "1",
            "online": true,
            "out_of_order": false
          }
        ]
      },
      "service": {
        "id": 34567,
        "name": "Dinner",
        "card_guarantee": false
      },
      "start_date": "2025-07-25T19:00:00",
      "total_cost": 23,
      "total_paid": 0
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🆕 Create a new order

<mark style="color:yellow;">**`POST`**</mark> `/`orders

Creates a new order for the specified property [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#5834ad1c-6718-4d4d-bfda-bb44aa45fd75)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Body**

<table><thead><tr><th width="207">Name</th><th width="188">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int</td><td>ID of the article (Dish)</td></tr><tr><td>reservation_id</td><td>int</td><td>ID of the reservation</td></tr><tr><td>name</td><td>string</td><td>Nome of the article</td></tr><tr><td>price</td><td>number</td><td>Price of the article</td></tr><tr><td>variations</td><td>array</td><td>List of selected variations (such as extra cheddar or extra bacon)</td></tr><tr><td>quantity</td><td>int</td><td>Ordered quantity of the item</td></tr><tr><td>notes</td><td>string</td><td>Additional notes for the order (no onion, no spicy)</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="201 Created" %}

```
[
    {
        "id": 453449,
        "reservation": 33435641,
        "insert_date": "2025-08-12T16:37:58.062",
        "status": "UNREAD",
        "article": {
            "id": 302829,
            "name": "Pizza Margherita",
            "price": 0,
            "image": "44477/1746202972857.jpg",
            "allergens": [],
            "category_id": 63534,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {}
        },
        "currency": "EUR",
        "quantity": 1,
        "total": 6
    }
]
```

{% endtab %}
{% endtabs %}

## 🔄 Update an order

<mark style="color:blue;">**`PUT`**</mark> `/orders/{order_id}`

Update the quantity order of a specific article [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#ec925de7-bdba-4795-a7e7-643887e33564)

**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Body**

<table><thead><tr><th width="207">Name</th><th width="188">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int</td><td>ID of the article (Dish)</td></tr><tr><td>reservation_id</td><td>int</td><td>ID of the reservation</td></tr><tr><td>name</td><td>string</td><td>Nome of the article</td></tr><tr><td>price</td><td>number</td><td>Price of the article</td></tr><tr><td>variations</td><td>array</td><td>List of selected variations (such as extra cheddar or extra bacon)</td></tr><tr><td>quantity</td><td>int</td><td>Ordered quantity of the item</td></tr><tr><td>notes</td><td>string</td><td>Additional notes for the order (no onion, no spicy)</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="201 Created" %}

```json
[
    {
        "id": 453449,
        "reservation": 33435641,
        "insert_date": "2025-08-12T16:37:58.062",
        "status": "UNREAD",
        "article": {
            "id": 302829,
            "name": "Pizza Margherita",
            "price": 0,
            "image": "44477/1746202972857.jpg",
            "allergens": [],
            "category_id": 63534,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {}
        },
        "currency": "EUR",
        "quantity": 1,
        "total": 6
    }
]
```

{% endtab %}
{% endtabs %}

## 🔄 Update order status

<mark style="color:purple;">**`PATCH`**</mark> `/`orders/{{order\_id}}/WAITING

Update the **status** of an existing article (dish) [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#9409fa11-ff34-49fd-b459-8300a7fa960b). \
\
**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Response**

{% tabs %}
{% tab title="200 Ok" %}

```json
{
  "data": [
    {
      "id": 452190,
      "reservation": 33319904,
      "insert_date": "2025-07-29T14:51:16",
      "status": "WAITING",
      "article": {
        "id": 313078,
        "name": "Pizza",
        "price": 0,
        "image": "1000173/1753370698219.jpg",
        "allergens": [],
        "category_id": 65614,
        "characteristics": [],
        "tax": 0,
        "translated_texts": {}
      },
      "currency": "EUR",
      "quantity": 4,
      "total": 40
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🔄 Update reservation order status

<mark style="color:purple;">**`PATCH`**</mark> `/`orders/reservation/{{reservation\_id}}/WAITING

Bulk update the status of all articles (dishes) belonging to the order associated with the specified reservation to **WAITING**, which is one of the possible order statuses [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#c5750d94-d5b9-4103-93e8-550c5948c80b).

\
**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Response**

{% tabs %}
{% tab title="200 Ok" %}

```json
{
  "data": [
    {
      "channel": "OCTOTABLE_BOOK",
      "create_time": "2025-07-24T17:20:26",
      "customer": {
        "id": 34112273,
        "first_name": "Elsie",
        "last_name": "Dillon",
        "email": "howe.weeks@gmail.nexus",
        "phone": "+393125450222"
      },
      "id": 33319904,
      "mode": "ROOM",
      "order": [
        {
          "id": 451917,
          "reservation": 33319904,
          "insert_date": "2025-07-25T15:48:54",
          "status": "WAITING",
          "article": {
            "id": 313080,
            "name": "Sanwich",
            "price": 3,
            "image": "1000173/1753370761583.jpg",
            "allergens": [],
            "category_id": 65614,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {},
            "variations": []
          },
          "currency": "EUR",
          "quantity": 1,
          "total": 3
        },
        {
          "id": 452190,
          "reservation": 33319904,
          "insert_date": "2025-07-29T14:51:16",
          "status": "WAITING",
          "article": {
            "id": 313078,
            "name": "Pizza",
            "price": 10,
            "image": "1000173/1753370698219.jpg",
            "allergens": [],
            "category_id": 65614,
            "characteristics": [],
            "tax": 0,
            "translated_texts": {},
            "variations": []
          },
          "currency": "EUR",
          "quantity": 4,
          "total": 40
        }
      ],
      "order_cost": 43,
      "room": {
        "id": 23694,
        "name": "Garden",
        "tables": [
          {
            "id": 204838,
            "name": "1",
            "online": true,
            "out_of_order": false
          }
        ]
      },
      "service": {
        "id": 34567,
        "name": "Dinner",
        "card_guarantee": false
      },
      "start_date": "2025-07-25T19:00:00",
      "total_cost": 43,
      "total_paid": 0
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🗑️ Delete an order

<mark style="color:red;">**`DELETE`**</mark> `/`orders/{{order\_id}}/reservation/{{reservation\_id}}

Delete a single article (`order_id`) from the order linked to the specified reservation (`reservation_id`). This does not delete the entire order, only the selected article [see more](https://documenter.getpostman.com/view/36615570/2sB2qZDgok#d41a431a-c673-483c-8fa4-c2c7281bb2a4).

\
**Headers**

| Name            | Value                |
| --------------- | -------------------- |
| `Content-Type`  | `application/json`   |
| `Authorization` | `Bearer <token>`     |
| `Property`      | `<your_property_id>` |

**Response**

{% tabs %}
{% tab title="200 Ok" %}

```json
{
  "data": [
    452190
  ]
}
```

{% endtab %}
{% endtabs %}

**📕 ADDITIONAL NOTES**&#x20;

In OctoTable, the term **order** always refers to a **single article** (menu item) linked to a specific reservation.

* The `order_id` identifies an individual article (dish) connected to that reservation.
* A complete customer order is therefore the **set of all orders (articles)** associated with the same `reservation_id`.

<mark style="color:red;">delivery\_mode</mark> **:** This parameter defines how the order will be fulfilled: **takeaway** (customer picks up at the restaurant), **delivery** (order is delivered to a specified address within configured limits), or **table order** (customer orders directly from their table using a QR code).

<mark style="color:red;">status\[]</mark> :

* **UNREAD** – The order has been added to the reservation but has not yet been sent to the kitchen. No action is triggered at this stage. This is the initial status of an order.
* **WAITING** – The order has been sent to the kitchen and can be printed from the kitchen printer. This status marks the order as official and ready to be prepared exactly as submitted.
* **PREPARING** – The kitchen is currently preparing the order. This status can be used to notify waiters of progress or inform the customer (for takeaway and delivery) that preparation has started.
* **READY** – The order has been prepared and is ready for pickup by the waiter, the delivery rider, or the customer (for takeaway).
* **DELIVERED** – The order has been delivered to the customer.

<mark style="color:red;">**category\_id**</mark> <mark style="color:$info;">:</mark> ID of the category the article belongs to (e.g., Starter, First Dish, Dessert).&#x20;

<mark style="color:red;">**allergens**</mark> : List of allergens contained in the article.&#x20;

<mark style="color:red;">**characteristics**</mark> : Specific characteristics of the dish, such as lactose-free, gluten-free, vegan, etc.

<mark style="color:red;">**tax**</mark> <mark style="color:$info;">:</mark> VAT rate associated with the product.

<mark style="color:red;">**translated\_texts**</mark> : Translated names of the article in the languages available in the system.

<mark style="color:red;">**variations**</mark> : Options that define the format or quantity of a dish or beverage.

* *Example:* For fries, you could have **Small portion** and **Large portion**.
* **Extra ingredients** – Optional additions such as cheese, sauces, toppings, etc., that can increase the base price of the product.

<mark style="color:red;">**total**</mark> : Total amount of the ordered articles only (unit price × quantity, plus any extras).\
\ <mark style="color:red;">order\_cost</mark> : Total cost of all items (dishes) included in the order. It represents the sum of the prices of the ordered articles, considering their quantity and any selected variations or extras.

<mark style="color:red;">**total\_cost**</mark> :  Final cost of the order, including order\_cost, plus any additional charges such as delivery fees or other service costs.

Total amount including additional costs, such as delivery fees.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://octotable-1.gitbook.io/octotable-api/getting-started-with-reservations/orders/get-orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.