# Manage your reservations

Abot octotable reservations:

* **Online Reservations**: These are made through our integrated **Booking Engine** and **Reserve with Google** feature.
  1. In Octotable, we manage reservations through both **online** and **offline** methods to offer flexibility and ease of use for both customers and restaurant managers.
  2. **Booking Engine**: The **Octotable Booking Engine** is a separate, standalone page that can be linked to from the restaurant’s website. The restaurant can either embed this page directly or add a button that redirects customers to the booking page. Customers can then select a room (rather than just a table), view available time slots, and complete their reservation directly on this page.
  3. **Reserve with Google**: This feature allows customers to make reservations directly from Google Search results and Google Maps. Customers can see a "Reserve a table" button in the search engine results or on the map listing, which allows them to book a table directly from there.
* **Offline Reservations**: In addition to online reservations, we also support **self reservations**. This means restaurant staff can manually create a reservation either through the **browser** or the **Octotable app**. This is ideal for phone bookings, walk-ins, or email reservations.

In summary, Octotable offers three ways to manage reservations: through the **Booking Engine** (linked or embedded on the website), **Reserve with Google** (from search results or Google Maps with a "Reserve a table" button), and **self reservations** via the browser or app. This ensures that restaurants can handle various booking methods with ease.

ℹ️ **The Booking Engine** is the core feature, allowing customers to make reservations, choose rooms, slot times, number of persons and cancel existing bookings.\
\
⚙️ **Use the base resource URL** for the following examples, or [see the complete collection](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

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

## 🔍 Find all reservations

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

Retrieves a list of all reservations for the specified property (e.g., restaurant) using the property ID [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**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>next_cursor</code></td><td>string</td><td>Pagination cursor</td></tr><tr><td><code>limit</code></td><td>int</td><td>Elements limit per page</td></tr><tr><td><code>start_date</code></td><td>date [YYYY-MM-DD]</td><td>Start day of search</td></tr><tr><td><pre><code>start_hour
</code></pre></td><td>[HH:MM:SS]</td><td>Starting hour of the reservation</td></tr><tr><td><code>end_date</code></td><td>date [YYYY-MM-DD]</td><td>End day of search</td></tr><tr><td><code>status[]</code></td><td>[WAITING, ACCEPTED, CANCELLED, CONFIRMED, EXPIRED, PREPAY, OUTOFORDER, REJECTED]</td><td>The status of reservation</td></tr><tr><td><code>text_search</code></td><td>string</td><td>The text search by customer name, last name or phone number</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>incoming</td><td>Boolean</td><td>Search criteria to retrieve incoming reservations</td></tr><tr><td>arrived</td><td>Boolean</td><td>Search criteria to retrieve arrived reservations</td></tr><tr><td>departed</td><td>Boolean</td><td>Search criteria to retrieve departed reservations</td></tr></tbody></table>

**Response**

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

```json
{
  "data": [
    {
      "id": 32992280,
      "pax": 2,
      "status": "CANCELLED",
      "customer": {
        "id": 33942074,
        "first_name": "Adam",
        "last_name": "Devis",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 33841,
        "name": "Custom dinner"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 23288,
        "name": "Sala Nuova"
      },
      "end_date": "2025-05-15T14:00:00",
      "last_status_change": "2025-05-14T17:06:46",
      "notes": "",
      "special_request": "",
      "start_date": "2025-05-15",
      "start_hour": "13:00:00",
      "tables": [
        {
          "id": 197934,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "online": true,
          "room_id": 23288
        }
      ],
      "waiting_list": false
    },
    {
      "id": 32992285,
      "pax": 2,
      "status": "CANCELLED",
      "customer": {
        "id": 33942079,
        "first_name": "Adam 2",
        "last_name": "Devis 2",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 33841,
        "name": "Custom dinner"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 23288,
        "name": "Sala Nuova"
      },
      "end_date": "2025-05-15T14:00:00",
      "last_status_change": "2025-05-14T17:09:40",
      "notes": "",
      "special_request": "",
      "start_date": "2025-05-15",
      "start_hour": "13:00:00",
      "tables": [
        {
          "id": 197934,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "online": true,
          "room_id": 23288
        }
      ],
      "waiting_list": false
    },
    {
      "id": 32992293,
      "pax": 2,
      "status": "CANCELLED",
      "customer": {
        "id": 33942086,
        "first_name": "Adam 2",
        "last_name": "Devis 2",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 33841,
        "name": "Custom dinner"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 23288,
        "name": "Sala Nuova"
      },
      "end_date": "2025-05-15T14:00:00",
      "last_status_change": "2025-05-14T17:09:44",
      "start_date": "2025-05-15",
      "start_hour": "13:00:00",
      "tables": [
        {
          "id": 197934,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "online": true,
          "room_id": 23288
        }
      ],
      "waiting_list": false
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🔍 Find reservation by ID

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

Retrieves a reservations by its ID [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Response**

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

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "data": [
        {
            "id": 31753958,
            "pax": 2,
            "status": "CONFIRMED",
            "customer": {
                "id": 33499559,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30911,
                "name": "Lunch"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21344,
                "name": "Secondary dining room"
            },
            "end_date": "2024-12-14T14:30:00",
            "start_day": "2024-12-14",
            "start_hour": "13:30:00",
            "tables": [
                {
                    "id": 172246,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21344
                }
            ],
            "waiting_list": false
        }
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

## 🆕 Create a new reservation

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

Creates a new reservation for the specified property using the provided reservation details [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Body**

<table><thead><tr><th width="256">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>start_date</code></td><td>date [YYYY-MM-DD]</td><td>The start date</td></tr><tr><td><code>start_hour</code></td><td>time [HH:mm:ss]</td><td>The start hour</td></tr><tr><td><code>pax</code></td><td>int</td><td>The number of person</td></tr><tr><td><code>channel</code></td><td>enum [OCTOTABLE_BOOK, OCTOTABLE_ADMIN]</td><td><strong>OCTOTABLE_BOOK</strong>: This indicates reservations made through the <strong>Booking Engine.</strong><br>resents reservations made through <strong>Reserve with Google.</strong><br><strong>OCTOTABLE_ADMIN</strong>: Refers to <strong>self reservations.</strong></td></tr><tr><td><code>customer</code></td><td>Customer </td><td>The customer who makes the reservation</td></tr><tr><td><code>customer.first_name</code></td><td>string</td><td>The customers first name</td></tr><tr><td><code>customer.last_name</code></td><td>string</td><td>The customer last name</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>The customers email</td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>The customers phone</td></tr><tr><td><code>service_id</code></td><td>int</td><td>The id of the selected service</td></tr><tr><td><code>room_id</code></td><td>int</td><td>The id of the selected room</td></tr><tr><td><code>table_ids</code></td><td>[int]</td><td>The list of ids of the selected tables</td></tr><tr><td><code>waiting_list</code></td><td>boolean</td><td>Keep reservation in waiting list</td></tr></tbody></table>

**Response**

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

```json
{
  "data": [
    {
      "id": 31753956,
      "pax": 2,
      "status": "WAITING",
      "customer": {
        "id": 33499557,
        "first_name": "Adam",
        "last_name": "Devis",
        "email": "adam.devis@email.com",
        "phone": "3332211456"
      },
      "service": {
        "id": 30907,
        "name": "Pranzo nuovo"
      },
      "channel": "OCTOTABLE_ADMIN",
      "room": {
        "id": 21343,
        "name": "main dining room"
      },
      "end_date": "2024-12-12T13:30:00",
      "start_date": "2024-12-12",
      "start_hour": "12:30:00",
      "tables": [
        {
          "id": 172245,
          "name": "T8",
          "bookable": true,
          "free": true,
          "group": false,
          "room_id": 21343
        }
      ],
      "waiting_list": false
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## 🟢 Enable Google Engine

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

Activates the Google Engine for a specified property [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Body**

| Name                   | Type    | Description              |
| ---------------------- | ------- | ------------------------ |
| `enable_google_engine` | boolean | Enable the google engine |

**Response**

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

```json
{
  "status": "ACCEPTED"
}
```

{% endtab %}
{% endtabs %}

## 🔄 Update a reservation

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

Update an existing reservation [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Body**

<table><thead><tr><th width="256">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>start_day</code></td><td>date [YYYY-MM-DD ]</td><td>The start day</td></tr><tr><td><code>start_hour</code></td><td>time [HH:mm:ss]</td><td>The start hour</td></tr><tr><td><code>pax</code></td><td>int</td><td>The number of person</td></tr><tr><td><code>service_id</code></td><td>int</td><td>The id of the selected service</td></tr><tr><td><code>room_id</code></td><td>int</td><td>The id of the selected room</td></tr><tr><td><code>table_ids</code></td><td>[int]</td><td>The list of ids of the selected tables</td></tr></tbody></table>

**Response**

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

```json
{
    "data": [
        {
            "id": 31753936,
            "pax": 2,
            "status": "CONFIRMED",
            "customer": {
                "id": 3255826,
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@demo.com",
                "phone": "55555555555"
            },
            "service": {
                "id": 17884,
                "name": "Breakfast"
            },
            "channel": "OCTOTABLE_ADMIN",
            "start_day": "2024-10-30",
            "start_hour": "18:00:00"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🔄  Check in

<mark style="color:purple;">**`PATCH`**</mark> `/reservations/{reservation_id}/checkin`

Customers check-in [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Query params**

| Name   | Type    | Description                                  |
| ------ | ------- | -------------------------------------------- |
| `undo` | boolean | Undo check in if it has been made by mistake |

**Response**

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

```json
{
    "data": [
        {
            "id": 31753956,
            "pax": 2,
            "status": "ACCEPTED",
            "customer": {
                "id": 33499557,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30907,
                "name": "Pranzo nuovo"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21343,
                "name": "main dining room"
            },
            "checkin_date": "2024-12-12T17:04:04.564",
            "end_date": "2024-12-12T13:30:00",
            "expiration_date": "2024-12-12T17:13:49",
            "start_day": "2024-12-12",
            "start_hour": "12:30:00",
            "tables": [
                {
                    "id": 172245,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21343
                }
            ],
            "waiting_list": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🔄 Check out

<mark style="color:purple;">**`PATCH`**</mark> `/reservations/{reservation_id}/checkout`

Customers check out [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Query param**

| Name   | Type    | Description                                   |
| ------ | ------- | --------------------------------------------- |
| `undo` | boolean | Undo check out if it has been made by mistake |

**Response**

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

```json
{
    "data": [
        {
            "id": 31753958,
            "pax": 2,
            "status": "CONFIRMED",
            "customer": {
                "id": 33499559,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30911,
                "name": "Lunch"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21344,
                "name": "Secondary dining room"
            },
            "end_date": "2024-12-14T14:30:00",
            "start_day": "2024-12-14",
            "start_hour": "13:30:00",
            "tables": [
                {
                    "id": 172246,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21344
                }
            ],
            "waiting_list": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🔄 Update status

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

Update the status of the reservation in waiting list. If on the waiting list, the reservation should become accepted, declined, or confirmed [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Query param**

| Name     | Type | Description                                   |
| -------- | ---- | --------------------------------------------- |
| `status` | enum | The status of the reservation in waiting list |

**Response**

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

```json
{
    "data": [
        {
            "id": 31753956,
            "pax": 2,
            "status": "WAITING",
            "customer": {
                "id": 33499557,
                "first_name": "Adam",
                "last_name": "Devis",
                "email": "adam.devis@email.com",
                "phone": "3332211456"
            },
            "service": {
                "id": 30907,
                "name": "Pranzo nuovo"
            },
            "channel": "OCTOTABLE_ADMIN",
            "room": {
                "id": 21343,
                "name": "main dining room"
            },
            "end_date": "2024-12-12T13:30:00",
            "start_day": "2024-12-12",
            "start_hour": "12:30:00",
            "tables": [
                {
                    "id": 172245,
                    "name": "T8",
                    "bookable": true,
                    "free": true,
                    "group": false,
                    "room_id": 21343
                }
            ],
            "waiting_list": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## 🗑️ Delete a reservation

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

Delete a reservation [see more](https://documenter.getpostman.com/view/50380496/2sB3dK1YWg#79ffebf1-b333-4f0d-981b-3299ae74856e)

**Headers**

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

**Response**

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

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

{% endtab %}
{% endtabs %}

**📕 ADDITIONAL NOTES**&#x20;

**Tables**&#x20;

* <mark style="color:red;">**Bookable / Online**</mark>:\
  These parameters indicate whether a table can be booked online (via the booking engine or Reserve with Google) or only through manual methods such as phone or walk-in (offline).
* <mark style="color:red;">**Free**</mark>:\
  A table is considered *free* if it has no active reservation during the selected time slot. This status is based on the `average_stay` setting.\
  For example, if the average stay is 60 minutes and a reservation starts at 1:00 p.m., the table is marked as occupied from 1:00 p.m. to 2:00 p.m. However, it will also be considered unavailable starting from 12:00 p.m., in order to respect the buffer time before the next reservation.
* <mark style="color:red;">**Group**</mark>:\
  Indicates whether the table is a grouped table (i.e. a combination of two or more individual tables).
  * **Group = true** → The table is formed by merging smaller tables (e.g., *Indoor 1* {2 pax} + *Indoor 2* {2 pax} = *Indoor 1+2* {4 pax}).
  * **Group = false** → It is a standalone table.
* <mark style="color:red;">**Best\_Choice**</mark>:\
  This parameter helps the system determine the most suitable table for a given party size. The goal is to optimize table usage by selecting the table that best fits the number of guests (e.g., assigning a 2-pax table to a 2-person reservation instead of a 4-pax table).


---

# 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/manage-your-reservations.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.