> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/bookings/list.md).

# Booking List

Retrieve a paginated list of bookings with flexible filters for status, guest, and date ranges.

Retrieve a paginated list of bookings for your property. You can filter by status, guest, or stay date ranges.

To keep another system in sync, don't re-read every page: ask for [only the bookings that changed](#only-the-bookings-that-changed).

#### Endpoint

```http
GET /api/v1/client/bookings
```

#### Query Parameters

<table><thead><tr><th width="120">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>page</code></td><td>integer</td><td>The page number to retrieve (default: 1).</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Results per page, 1 to 500 (default: 10).</td></tr><tr><td><code>status</code></td><td>string</td><td>Filter by booking status (for example <code>reserved</code>, <code>confirmed</code>, <code>paid</code>, <code>cancelled</code>, or a status your property created). Case, spaces, <code>-</code> and <code>_</code> don't matter, so <code>no_show</code> finds <code>noShow</code> and <code>check_out</code> finds <code>check-out</code>.</td></tr><tr><td><code>guest_id</code></td><td>string</td><td>Filter by the guest's <code>guestId</code> as returned by the <a href="https://docs.hostelmate.co/api-documentation/guests/get.md">Guests API</a>. This is <strong>not</strong> the <code>guest.id</code> embedded in booking responses — see note below.</td></tr><tr><td><code>start_date</code></td><td>string</td><td>Filter bookings with stay dates on or after this date (YYYY-MM-DD).</td></tr><tr><td><code>end_date</code></td><td>string</td><td>Filter bookings with stay dates on or before this date (YYYY-MM-DD).</td></tr></tbody></table>

***

#### Example Request

```bash
curl "/api/v1/client/bookings?status=confirmed&limit=2" \
  -H "X-API-Key: <your_api_key>"
```

#### Example Response (200 OK)

```json
{
  "results": [
    {
      "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
      "status": "confirmed",
      "channel": "Booking",
      "checked_in": false,
      "total": 52000,
      "created": "2025-10-01T10:00:00Z",
      "updated": "2025-10-02T11:05:13Z",
      "description": "Premium Room choice",
      "guest": {
        "id": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone": "+123456789"
      },
      "stay_dates": [
        {
          "date": "2025-12-19",
          "amount": 26000,
          "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
          "bed": "bb9c708a-2695-435f-a1eb-1bf61381ad77"
        },
        {
          "date": "2025-12-20",
          "amount": 26000,
          "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
          "bed": "bb9c708a-2695-435f-a1eb-1bf61381ad77"
        }
      ]
    }
  ],
  "total_count": 1,
  "total_pages": 1,
  "current_page": 1
}
```

> **Note on Amounts**: All amount fields (`total`, `stay_dates[].amount`) are integers in **minor units** (e.g., `52000` = 520.00). This is different from the Payments API, which uses decimal strings (e.g., `"520.00"`).

> **`channel`**: where the booking came from, exactly as your booking list shows it. Bookings from your channels use the channel's name, for example `Booking` (Booking.com), `HostelWorld`, `Agoda`, `CTrip` (Trip.com), `Expedia` or `Airbnb`. Your booking page's bookings are `Website`, bookings made through this API are `ClientAPI`, and bookings your staff enter carry the source they picked, such as `WalkIn`, `Extension` or a source your property added. `null` when the booking has no nights.
>
> **`checked_in`**: `true` when the booking's `status` is `checkInPaid` (Check In Paid). Your staff set it in the calendar, or you can set it with [Update Booking](https://docs.hostelmate.co/api-documentation/bookings/update.md#update-status-or-notes). Statuses your property created itself are not counted, so `false` means "not marked as checked in", not "has not arrived".

> **Note on `guest.id`**: The `id` field inside the `guest` object in booking responses is an internal booking reference — it is **not** the same as the `guestId` used by the Guests API. Passing this value to `GET /api/v1/client/guests/{guestId}` will return `404`. To look up a guest's full profile, use [Search Guests](https://docs.hostelmate.co/api-documentation/guests/get.md) by email or name, and use the `guestId` field from that response.

#### Error Codes

<table><thead><tr><th width="80">HTTP</th><th width="190">Code</th><th>When</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td><code>page</code> or <code>limit</code> is not a whole number, or <code>limit</code> is not from 1 to 500, or <code>guest_id</code> is not a UUID. The <code>message</code> says which.</td></tr><tr><td>422</td><td><code>invalid_date_format</code></td><td><code>start_date</code> or <code>end_date</code> is not a date like <code>2026-11-01</code>.</td></tr><tr><td>401 / 403 / 429</td><td></td><td>See <a href="https://docs.hostelmate.co/api-documentation/authentication.md">Authentication</a>.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Something failed on our side. Retry with backoff.</td></tr></tbody></table>

> **Pages:** a `page` past the last one (or below 1) returns the last page.

***

## Only the bookings that changed

Instead of reading every page each time, ask for the bookings that changed since your last sync.

#### How to sync

1. **First time:** call with `updated_since` set to how far back you need, for example `2000-01-01T00:00:00Z` for everything.
2. **While `has_more` is `true`:** call again right away with `cursor` set to the `next_cursor` you got.
3. **When `has_more` is `false`:** you're up to date. Save the last `next_cursor`.
4. **Next sync:** call with `cursor` set to the saved `next_cursor`, then repeat from step 2.

```http
GET /api/v1/client/bookings?updated_since=2026-11-01T08:00:00Z&limit=500
GET /api/v1/client/bookings?cursor=<next_cursor>&limit=500
```

#### Query Parameters

<table><thead><tr><th width="140">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>updated_since</code></td><td>string</td><td>A time with a time zone, like <code>2026-11-01T08:00:00Z</code>. Bookings that changed at or after it are returned. With an offset like <code>+04:00</code>, encode the <code>+</code> as <code>%2B</code> (a bare <code>+</code> also works after a <code>T</code> time).</td></tr><tr><td><code>cursor</code></td><td>string</td><td>The <code>next_cursor</code> from your previous call. Send it instead of <code>updated_since</code>, never with it.</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Results per call, 1 to 500 (default: 100). For a first full sync, 500 is fastest.</td></tr></tbody></table>

`page`, `status`, `guest_id`, `start_date` and `end_date` can't be used here: a booking that stops matching a filter would silently drop out of your sync.

#### Example Response (200 OK)

```json
{
  "results": [
    {
      "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
      "status": "confirmed",
      "channel": "Booking",
      "checked_in": false,
      "total": 52000,
      "created": "2025-10-01T10:00:00Z",
      "updated": "2025-10-02T11:05:13Z",
      "description": "Premium Room choice",
      "guest": { "id": "7f99c230-8f64-4ecb-8804-d9ea5496bf63", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+123456789" },
      "stay_dates": [ { "date": "2025-12-19", "amount": 26000, "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0", "bed": "bb9c708a-2695-435f-a1eb-1bf61381ad77" } ],
      "changed_at": "2026-11-01T08:14:02.512331Z"
    }
  ],
  "next_cursor": "eyJ0IjogIjIwMjYtMTEtMDFUMDg6MTQ6MDIuNTEyMzMxKzAwOjAwIiwgImlkIjogImU3YjdmNmJi...",
  "has_more": false
}
```

Each booking has the same fields as in the list above, plus `changed_at`.

<table><thead><tr><th width="160">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>results[].changed_at</code></td><td>string</td><td>When the booking last changed: the booking itself, its nights, its guest, or its history.</td></tr><tr><td><code>next_cursor</code></td><td>string</td><td>Where to continue. Save it; it never expires.</td></tr><tr><td><code>has_more</code></td><td>boolean</td><td><code>true</code> when more changes are waiting right now.</td></tr></tbody></table>

#### Good to know

* Results come oldest change first.
* A booking that changes again while you page moves to the end. You see it again and miss nothing, so treat each result as "the latest version of this booking".
* Changes show up about a minute after they happen.
* Bookings you delete through the API don't appear here. Your `DELETE` call already told you about them.

#### Error Codes

<table><thead><tr><th width="80">HTTP</th><th width="190">Code</th><th>When</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td><code>updated_since</code> has no time zone, <code>updated_since</code> and <code>cursor</code> are sent together, a filter or <code>page</code> is added, or <code>limit</code> is not from 1 to 500.</td></tr><tr><td>400</td><td><code>invalid_cursor</code></td><td>The cursor is not one we gave you. Start again with <code>updated_since</code>.</td></tr><tr><td>422</td><td><code>invalid_date_format</code></td><td><code>updated_since</code> can't be read.</td></tr><tr><td>401 / 403 / 429</td><td></td><td>See <a href="https://docs.hostelmate.co/api-documentation/authentication.md">Authentication</a>.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Something failed on our side. Retry with backoff.</td></tr></tbody></table>
