Available now

Reservations

The Reservations API gives you full lifecycle control over guest bookings — create, confirm, check-in, check-out, and cancel. Every reservation belongs to a property and optionally links to a guest profile.

The Reservation object

idstringUnique reservation ID (ULID).

confirmation_numberstringHuman-readable confirmation code, e.g. ESC-A1B2C3D4.

property_idstringID of the property this reservation belongs to.

guest_idstring | nullLinked guest profile ID, if any.

statusenumpending · confirmed · checked_in · checked_out · cancelled · no_show

sourceenumBooking origin: direct · ota · gds · corporate · group · walk_in

room_typestringRoom or unit type, e.g. Ocean Suite.

room_numberstring | nullAssigned room number, if known at booking time.

adultsintegerNumber of adults. Minimum 1.

childrenintegerNumber of children. Default 0.

check_in_datestringArrival date in YYYY-MM-DD format.

check_out_datestringDeparture date in YYYY-MM-DD format.

nightsintegerLength of stay in nights.

rate_per_nightfloatNightly rate before taxes/fees.

total_amountfloatTotal booking value.

paid_amountfloatAmount paid to date.

currencystringISO 4217 currency code. Default USD.

special_requestsstring | nullFree-text special requests from the guest.

extra_dataobjectArbitrary metadata object for OTA references, channel IDs, etc.

checked_in_atdatetime | nullTimestamp set when guest checks in.

checked_out_atdatetime | nullTimestamp set when guest checks out.

cancelled_atdatetime | nullTimestamp set on cancellation.

created_atdatetimeISO 8601 creation timestamp.

updated_atdatetimeISO 8601 last-modified timestamp.

Endpoints

POST/v1/reservationsCreate a reservation

Create a new reservation for this property. Returns the created reservation including its generated confirmation number.

Request Body

room_typestringRoom or unit type name. Required.

check_in_datestringArrival date (YYYY-MM-DD). Required.

check_out_datestringDeparture date (YYYY-MM-DD). Required.

nightsintegerLength of stay. Required.

rate_per_nightfloatNightly rate. Required.

total_amountfloatTotal booking value. Required.

guest_idstringLink to an existing guest profile. Optional.

room_numberstringAssigned room. Optional.

adultsintegerNumber of adults. Default 1.

childrenintegerNumber of children. Default 0.

sourcestringBooking source. Default direct.

special_requestsstringFree-text notes from guest. Optional.

currencystringISO 4217 code. Default USD.

extra_dataobjectArbitrary metadata. Optional.

bash

curl -X POST https://api.escapelife.ai/v1/reservations \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type": "Ocean Suite",
    "check_in_date": "2026-07-14",
    "check_out_date": "2026-07-18",
    "nights": 4,
    "rate_per_night": 710,
    "total_amount": 2840,
    "source": "direct",
    "adults": 2
  }'

Response

{
  "id": "01HXZ8K3MNJQ7VPBR2F5C4DTWS",
  "confirmation_number": "ESC-A1B2C3D4",
  "property_id": "01HXZ8K3MN...",
  "guest_id": null,
  "status": "confirmed",
  "source": "direct",
  "room_type": "Ocean Suite",
  "room_number": null,
  "adults": 2,
  "children": 0,
  "check_in_date": "2026-07-14",
  "check_out_date": "2026-07-18",
  "nights": 4,
  "rate_per_night": 710.0,
  "total_amount": 2840.0,
  "paid_amount": 0.0,
  "currency": "USD",
  "created_at": "2026-03-16T13:00:00Z",
  "updated_at": "2026-03-16T13:00:00Z"
}

GET/v1/reservationsList reservations

Return all reservations for this property. Supports status filter and check-in date filter.

Path / Query Parameters

statusstringFilter by status: pending, confirmed, checked_in, checked_out, cancelled, no_show.

check_in_datestringFilter by check-in date (YYYY-MM-DD).

limitintegerMax results (1–200). Default 50.

offsetintegerPagination offset. Default 0.

GET/v1/reservations/summaryOccupancy & revenue summary

Returns reservation counts grouped by status and total revenue across all non-cancelled bookings.

Response

{
  "by_status": {
    "confirmed": 84,
    "checked_in": 12,
    "checked_out": 201,
    "cancelled": 8
  },
  "total_revenue": 284320.0
}

GET/v1/reservations/{reservation_id}Get a reservation

Path / Query Parameters

reservation_idstringrequiredReservation ID (ULID).

PATCH/v1/reservations/{reservation_id}Update a reservation

Partial update — only included fields are modified. Use the dedicated action endpoints to change status.

Path / Query Parameters

reservation_idstringrequiredReservation ID.

Request Body

room_numberstringAssign or update room number.

rate_per_nightfloatUpdate rate.

total_amountfloatUpdate total.

paid_amountfloatRecord a payment.

special_requestsstringUpdate special requests.

notesstringInternal notes.

Status transitions

Use dedicated action endpoints to move a reservation through its lifecycle. Status transitions are validated server-side.

POST/v1/reservations/{reservation_id}/check-inCheck in

Transitions status from confirmed or pending → checked_in. Sets checked_in_at timestamp.

Path / Query Parameters

reservation_idstringrequiredReservation ID.

POST/v1/reservations/{reservation_id}/check-outCheck out

Transitions status from checked_in → checked_out. Sets checked_out_at timestamp.

Path / Query Parameters

reservation_idstringrequiredReservation ID.

POST/v1/reservations/{reservation_id}/cancelCancel

Cancels any non-completed reservation. Sets cancelled_at timestamp. Cannot cancel checked_out or already-cancelled reservations.

Path / Query Parameters

reservation_idstringrequiredReservation ID.

Status flow

pending→confirmed→checked_in→checked_out

Any non-completed status can also transition to cancelled or no_show.

Webhooks fired by this module

reservation.created

New reservation created.

reservation.updated

Reservation fields updated.

reservation.checked_in

Guest checked in.

reservation.checked_out

Guest checked out.

reservation.cancelled

Reservation cancelled.