> 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 for your property. You can filter by status, guest, or stay date ranges.

#### 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>Number of results per page (default: 10).</td></tr><tr><td><code>status</code></td><td>string</td><td>Filter by booking status. Allowed values: <code>confirmed</code>, <code>cancelled</code>, <code>paid</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://github.com/DavidSamir/doc-hostelmate/blob/main/api-documentation/bookings/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",
      "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"`).

> **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](/api-documentation/guests/get.md) by email or name, and use the `guestId` field from that response.