Booking List

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

Endpoint

GET /api/v1/client/bookings

Query Parameters

Parameter	Type	Description
page	integer	The page number to retrieve (default: 1).
limit	integer	Number of results per page (default: 10).
status	string	Filter by booking status. Allowed values: confirmed, cancelled, paid.
guest_id	string	Filter by the guest's guestId as returned by the Guests API. This is not the guest.id embedded in booking responses — see note below.
start_date	string	Filter bookings with stay dates on or after this date (YYYY-MM-DD).
end_date	string	Filter bookings with stay dates on or before this date (YYYY-MM-DD).

---

Example Request

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

Example Response (200 OK)

{
  "results": [
    {
      "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
      "status": "confirmed",
      "total": 52000,
      "created": "2025-10-01T10:00:00Z",
      "updated": "2025-10-02T11:05:13Z",
      "paidDays": 2,
      "description": "Premium Room choice",
      "guest": {
        "id": "7f99c230-8f64-4ecb-8804-d9ea5496bf63",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone": "[phone]"
      },
      "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 by email or name, and use the guestId field from that response.