Availability
Search priced offers for a stay. Each offer is a room type on a rate plan, with the night-by-night price, fees, tax and the total to book at.
Search offers
/properties/{property_id}/offersavailability:readOperation offer.searchReturns what can be booked for the dates and guests you give: each room type with a free room and enough space, on its own rate and on each rate plan it is sold on, priced by the hotel's pricing engine. This is the same engine the front desk and the hotel's booking page use, so your price matches the hotel's.
Parameters
YYYY-MM-DD. Not before the hotel's today.arrival, at most 60 nights later.1.0.Example
curl -X GET "https://api.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/offers?arrival=2026-10-31&departure=2026-11-02&adults=2" \
-H "Authorization: Bearer cbk_••••"{
"property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
"arrival": "2026-10-31",
"departure": "2026-11-02",
"nights": 2,
"adults": 2,
"children": 0,
"offers": [
{
"room_type": {
"id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
"name": "Standard",
"max_occupancy": 2
},
"rate_plan": null,
"available": 6,
"currency": "USD",
"nights": [
{
"date": "2026-10-31",
"price": 90.0
},
{
"date": "2026-11-01",
"price": 90.0
}
],
"room_total": 180.0,
"fees": [],
"tax": {
"rate": 0.0,
"included": false,
"amount": 0.0
},
"total": 180.0
},
{
"room_type": {
"id": "cd4932a5-a172-4147-bfd6-fcd79a42af11",
"name": "Deluxe",
"max_occupancy": 3
},
"rate_plan": null,
"available": 4,
"currency": "USD",
"nights": [
{
"date": "2026-10-31",
"price": 140.0
},
{
"date": "2026-11-01",
"price": 140.0
}
],
"room_total": 280.0,
"fees": [],
"tax": {
"rate": 0.0,
"included": false,
"amount": 0.0
},
"total": 280.0
}
// ... one more (Suite, 480.0)
]
}The offer object
| Field | Meaning |
|---|---|
room_type | id, name, max_occupancy |
rate_plan | null for the room type's own rate, or {"id", "name", "meal_plan", "refundable"} |
available | Rooms of this type free for every night of the stay |
nights[] | {"date", "price"}, one per night, from the hotel's pricing engine, including the rate plan's price |
room_total | The sum of nights |
fees[] | {"name", "amount"}: the hotel's per-stay fees, such as a cleaning fee |
tax | rate (percent), included (already inside the prices), amount |
total | What the guest pays: room_total plus fees, plus tax when it is not included |
Offers are sorted by total, cheapest first. The same room type appears once per rate plan it is sold on, plus once on its own rate (rate_plan: null).
What is left out
An offer is only returned if it can actually be booked. These are left out, without an error:
- Room types that are inactive, have no free room for every night, or are too small for
adultspluschildren(or over theirmax_adultsormax_children). - Combinations that break the hotel's rules: a night closed to new bookings, the arrival night's minimum or maximum stay, or the rate plan's
min_stay_nightsandmax_stay_nights.
An empty offers list means nothing can be booked for those dates and guests.
Book at the total you showed
Prices can change between the search and the booking. Pass the offer's total back as expected_total when you create the reservation. If the price has moved, nothing is booked and you get 409 with the new total, so you can show the guest the new price instead of charging a surprise.
Offers do not include extras. If you book with extras, the price check covers them too: add their price (and any tax on them) to expected_total, or book without them and use reservation.addExtra afterwards.
Errors
| Status | detail | When |
|---|---|---|
400 | Check-out date must be after check-in date. | departure is not after arrival |
400 | Offers are for stays of up to 60 nights. | The stay is longer than 60 nights |
400 | The arrival date has passed. | arrival is before the hotel's today |
403 | The app token lacks availability:read | |
404 | Property not found | Not the credential's property |
422 | arrival or departure missing or not a date; adults or children out of range |
Building something?