ChatBedsРазработчикам
Справочник API

Эта страница ещё не переведена, поэтому вы читаете английскую версию.

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

GET/properties/{property_id}/offers
Scope availability:readOperation offer.search

Returns 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

property_id uuid (path)required
The property.
arrival date (query)required
The first night, YYYY-MM-DD. Not before the hotel's today.
departure date (query)required
The day the guest leaves. After arrival, at most 60 nights later.
adults integer (query)
1 to 20. Default 1.
children integer (query)
0 to 20. Default 0.
child_ages integer, repeated (query)
Each child's age, 0 to 17: child_ages=4&child_ages=9, as many as children. Children under 2 are infants: free and not counted against the room's size. Children are priced by the room's age bands (see pricing on room types). Without ages, every child counts as a guest.
room_type_id uuid (query)
Only this room type.
promo_code string (query)
A promo code the guest typed, like SUMMER20. Offers it applies to come lower, with promo saying the code, what it is and what it took off. If it applies to none, promo_error says why ("The code SUMMER20 is for stays of 2 nights or more.").
rate_code string (query)
A corporate rate code, like IBM2026. Opens the hotel's private rate plans with that code (rate_plan.private is true). Without it they are never offered.

Example

Request
curl -X GET "https://app.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_••••"
200 OK
{
  "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

FieldMeaning
room_typeid, name, max_occupancy
rate_plannull for the room type's own rate, or {"id", "name", "meal_plan", "refundable"}
availableRooms of this type free for every night of the stay. Rooms the hotel holds for a group (until the group's release date) and rooms out of order are not counted
nights[]{"date", "price"}, one per night, from the hotel's pricing engine, including the rate plan's price
room_totalThe sum of nights
fees[]{"name", "amount"}: the hotel's per-stay fees, such as a cleaning fee
taxrate (percent), included (already inside the prices), amount
totalWhat 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 adults plus the children over 2 (or over their max_adults or max_children), and stays the hotel's children policy refuses (adults only, or children from an age).

Each offer's room_type also gives max_adults, max_children, cots and extra_beds; each night's extra_guests is the part of its price for guests over the room's base occupancy.

  • Combinations that break the hotel's rules: a night closed to new bookings, an arrival night closed to arrivals, a departure morning closed to departures, the arrival night's minimum or maximum stay, or the rate plan's min_stay_nights and max_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

StatusdetailWhen
400Check-out date must be after check-in date.departure is not after arrival
400Offers are for stays of up to 60 nights.The stay is longer than 60 nights
400The arrival date has passed.arrival is before the hotel's today
403The app token lacks availability:read
404Property not foundNot the credential's property
422arrival or departure missing or not a date; adults or children out of range

Что-то создаёте?

На этой странице