Create or update inventory, rates and restrictions

Use the availability endpoint to specify a property's availability for specific rooms, rates, and dates.

Each request can contain the following information:

  • The number of available rooms for sale on specified dates.
  • The price for the room, depending on the number of occupants.
  • Restrictions on the length of the stay and check-in and check-out dates.

For more information on pricing models, see Pricing Models.

Specify at least 12 months of availability

You should specify the availability of your connected properties at least 12 months in advance. In other words, on 1 January 2023, you should specify availability until at least 31 December 2023.

Setting up availability

Use the availability endpoint to:

  • Set prices by specifying room type, date, rate and restrictions, if any.
  • Update only the number of rooms to sell (roomstosell) for a room type. Note that the number of rooms applies to all rates when the room type has multiple prices set using different room and rate combinations.
  • [Open or close][close-room] a room type or a combination of room type and rate.
POST
https://supply-xml.booking.com/hotels/xml/availability

Difference between availability endpoint v1.0 and v1.1

The availability endpoint has two versions currently. When migrating to the v1.1 availability endpoint, you get:

For a complete list of new and changed error codes, see the migration guide.

Header parameter

Header Description Type Required/
Optional
Notes
Accept-Version Specify the version number to get the API functionality specific to that version. string optional Supports the following values:
- 1.1: New version.
- 1.0: Previous version.

Sample header

POST 'https://supply-xml.booking.com/hotels/xml/availability' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblhWTdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'

Closing room type vs. room and rate combination

You can close availability at the:

  • room type level: Useful when removing availability for all rooms of a room type that has multiple rate combinations.
  • room type and rate combination level: Useful when removing availability for a room type satisfying a specific rate combination.

Consider the following inventory:

Room type Rate Price Date period Rooms to sell
Villa Summer rate 110 Jul 15 - Aug 31 10
Villa Peak season rate 120 Aug 05 - Aug 20 10
Villa Off season rate 90 Nov 01 - Dec 10 10

Closing room type and rate combination

To close the availability of the Villa so that guests don't see availability from Nov 01 - Dec 10, you must close the room type (Villa) and rate combination (Off season rate) by providing the following parameters: room, date, rate, closed

Closing a room type

To close the availability of a specific room type, say Villa, so that guests don't see availability for a specific period, you must close the room type (Villa) by providing the following parameters: room, date, closed.

Once a room is closed you must open it before creating availability

Before creating availability for a room that is closed, you must use the availability endpoint to open the room. Otherwise, the request to create availability completes successfully, but guests will not be able to see the availability as the room is still closed.

Specifying currency code with availability

For guests to see the correct prices on Booking.com, it is recommended to send the currency code along with prices while creating availability using the Rates & Availability APIs. In case the value of the currencycode field does not match the default currency of the property, the API returns the CURRENCY_CODE_DONT_MATCH_HOTEL_CURRENCY error.

To retrieve the property details along with the configured currency code, use the GET OTA_HotelDescriptiveInfo endpoint.

Request body

Element Attribute Description Type Required Notes
request Root element. object required -
> room Contains details about the room. object required -
id The Booking.com room ID. integer required
>> date Specifies the date(s) (value), date range (from to), or mix of both to which the availability applies. datetime required Format: YYYY-MM-DD. We recommend specifying at least 12 months of availability.
value Specifies a single date. datetime required Format: YYYY-MM-DD.
NOTE: You can include multiple values (value) in the same date element.
from Specifies the starting date of a date range. datetime required Format: YYYY-MM-DD. Date must be before the date you specify in to. Please note, you can update for periods in the future and up to two day in the past, in the Central European Time (CET) timezone.
to Specifies the ending date of a date range, excluding the end date. datetime required Format: YYYY-MM-DD. You can specify up to 10 years of availability from the date you make the call.
NOTE: You should interpret date[to] as "up to and not including". In other words, a request with <date from="2019-08-27" to="2029-09-02" /> applies to all days from 27 August 2019 up to 1 September 2029.
>>> currencycode Specifies the property's local currency code. enumerated string optional We recommend providing the currency code. When provided, it must match the property's currency code.
>>> rate Contains details about the rate. integer required when price is set This field is optional if the update only specifies roomstosell. If restrictions or price is specified then rate is required.
NOTE: If your request includes rate, it is recommended to exclude roomstosell.
id The Booking.com rate ID. integer optional Use roomrates to retrieve a list of active rates for a property.
>>> roomstosell Specifies the number of rooms of this type that Booking.com can sell. The number of available rooms applies across all rates including prices set using other rates for the same room type. integer optional Maximum value: 254
NOTE: Setting a value greater than 255 implies that there are unlimited rooms available. Use other restrictions (such as closed) to prevent overbookings.
>>> min_advance_res The minimum number of days and/or hours that guests must book in advance (before the planned check-in or check-out date). The search date is counted as one of the days in the restriction length. string optional Maximum value: 360D. 
Examples: 4D = four days; 4D4H = four days and four hours.
NOTE: You must include rate[id] when updating min_advance_res. You cannot specify a negative amount of time.
>>> max_advance_res The maximum number of days and/or hours that guests may book in advance (before the planned check-in or check-out date). The search date is counted as one of the days in the restriction length. string optional Maximum value: 360D.
Examples: 4D = four days; 4D4H = four days and four hours.
NOTE: You must include rate[id] when updating max_advance_res. You cannot specify a negative amount of time.
>>> price The default price for the specified combination of room, date, and rate, in the property's local currency (as defined by Booking.com). float optional Format: ###.## (always two decimals)
NOTE: What is considered the default price depends on your pricing model. You cannot remove a price after it has been set. You cannot specify a negative price.
>>> price1 Only applicable when pricing type is standard. The price for one person, for the specified combination of room, date, and rate, in the property's local currency (as defined by Booking.com). float optional Format: ###.## (always two decimals)
NOTE: Don't use price1 for single rooms. You cannot remove price1 when roomstosell is equal to or greater than 1. You cannot specify a negative price.
>>> closed (v 1.0) Specifies whether the room is closed (not bookable) on the specified date, for the specified rate. integer optional Accepts: 1 (closed), 0 (open).
NOTE: See also Availability restrictions. Closing a room does not clear the value of roomstosell, price, or other fields. The values are preserved.
Once you close a room, make sure to open it before setting availability for it.
>>> closed (v 1.1) [Only applicable if you specify Accept-Version 1.1 in the header]Specifies whether all rooms of a room type are closed (not bookable) or only the specified room type and rate combination on the specified date depending on whether the rate ID is provided. integer optional Accepts: 1 (closed), 0 (open).
NOTE: See also Availability restrictions. Closing a room does not clear the value of roomstosell, price, or other fields. The values are preserved.
Once you close a room, make sure to open it before setting availability for it.
>>> minimumstay The minimum number of days a guest must book the specified room, for the specified rate, if the stay includes the specified date. integer optional Maximum value is the maximum allowed length of stay.
NOTE: Value must be less than maximumstay and maximumstay_arrival. See also Availability restrictions.
>>> minimumstay_arrival The minimum number of days a guest must book the specified room, for the specified rate, if they check in on the specified date. integer optional Maximum value is the maximum allowed length of stay.
NOTE: Value must be less than maximumstay and maximumstay_arrival. See also Availability restrictions.
>>> maximumstay The maximum number of days a guest may book the specified room, for the specified rate, if the stay includes the specified date. integer optional Maximum value is the maximum allowed length of stay.
NOTE: Value must be greater than minimumstay and minimumstay_arrival. See also Availability restrictions.
>>> maximumstay_arrival The maximum number of days a guest may book the specified room, for the specified rate, if they check in on the specified date. integer optional Maximum value is the maximum allowed length of stay.
NOTE: Value must be greater than minimumstay and minimumstay_arrival. See also Availability restrictions.
>>> exactstay_arrival The exact number of days a guest must book the specified room, for the specified rate, if they check in on the specified date. integer optional Maximum value is the maximum allowed length of stay.
NOTE: See also Availability restrictions.
>>> closedonarrival Specifies if the room is unavailable to book if the guest checks in on the specified date. integer optional Accepts: 1 (closed), 0 (open).
NOTE: See also Availability restrictions.
>>> closedondeparture Specifies if the room is unavailable to book if the guest checks out on the specified date. integer optional Accepts: 1 (closed), 0 (open).
NOTE: See also Availability restrictions.

Removing minimum and maximum length-of-stays

To remove an existing length-of-stay restriction you must send a request to update the minimumstay or maximumstay value to 0. You can encounter the following scenarios:

  • Update only <minimumstay>0</minimumstay> if you want to remove the minimum stay restriction.
  • Update only <maximumstay>0</maximumstay> if you want to remove the maximum stay restriction.
  • Update both if you want to remove minimum and maximum stay restrictions.

To reinstate restrictions, you must send another request with the value representing the desired amount of days for either or both length-of-stay restrictions.

Sample request

The request below specifies the following booking conditions for room type 1000202, with rate 12345, on 28 August, 2023:

  • The property has 1 room of this type available for sale (roomstosell).
  • The room is available to book on this date, for this rate, only if the stay is at least 2 nights, and at most 14 nights (minimumstay, maximumstay).
  • The room costs 135 (in the property's local currency) per night for one person, or 150 per night for the maximum number of persons.
  • The room is not available to book for this rate if the planned check-out date is 28 August (closedondeparture).
<request>
  <room id="1000202">
    <date value='2023-08-28'>
      <roomstosell>1</roomstosell>
    </date>
  </room>
  <room id="1000202">
    <date value="2023-08-28">
      <currencycode>EUR</currencycode>
      <rate id="12345"/>
      <price>150.00</price>
      <price1>135.00</price1>
      <closed>0</closed>
      <minimumstay>2</minimumstay>
      <maximumstay>14</maximumstay>
      <closedonarrival>0</closedonarrival>
      <closedondeparture>1</closedondeparture>
    </date>
  </room>
</request>

Keep roomstosell and rate separate

If your request includes both roomstosell and rate, we recommend putting each in its own room element. This makes it more obvious that the value of roomstosell applies to the room as a whole, and not to an individual rate.

Response body

Field Attribute Description Type Notes
> ok Indicates a successful request. object Only returned if there are no errors elements.
> availability Root element for error responses. object -
>> errors Groups a list of individual errors. object -
>>> error List details of individual errors object -
code Returns an error code for an error. integer -
>>>> message Returns a user-friendly error message with a possible resolution to the error. string -
>>>> details Contains additional error details. object -
>>>>> dates Specifies the incorrect date to fix. date Follows the format YYYY-MM-DD
> warning One or more warning messages, separated by ;. string Warnings can occur even if the response contains ok.

Sample responses

Success

A successful response looks like this:

<ok></ok>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXX==] -->

HTTP/1.1 200 OK does not always mean 'success'

A request can contain more than one update. When processing a request containing multiple updates with at least one invalid update, the API returns a HTTP status 200 with error response. If all updates are invalid, then the API returns a HTTP status 400 with error response.

HTTP/1.1 400 Bad request

<availability>
    <errors>
        <error code="NOT_A_VALID_DATE">
            <message>Dates should be in YYYY-MM-DD format, not before '2023-01-08',
                and not be past '2033-12-31'. The data should also be valid.</message>
            <details>
                <dates>2022-12-12</dates>
            </details>
        </error>
        <error code="RATE_NOT_ACTIVE_FOR_ROOM">
            <message>Rate '1234' is not active for room '4567'</message>
            <details>
                <room_ids>4567</room_ids>
                <hotel_ids>789</hotel_ids>
                <dates>2023-05-02</dates>
                <rate_ids>1234</rate_ids>
            </details>
        </error>
    </errors>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->

Partly successful request

A response with status code HTTP/1.1 200 OK may still have errors in the body:

<availability>
    <errors>
        <error code="NOT_A_VALID_DATE">
            <message>Dates should be in YYYY-MM-DD format, not before '2023-01-08',
                and not be past '2033-12-31'. The data should also be valid.</message>
            <details>
                <dates>2022-12-12</dates>
            </details>
        </error>
    </errors>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->

Successful request with warnings

A response with status code HTTP/1.1 200 OK may contain warnings:

<availability>
    <warnings>
        <warning code="WARN_TOO_LARGE_NUMBER_ROOMS_TO_SELL">
            <details>
                <hotel_ids>1234</hotel_ids>
                <room_ids>12345</room_ids>
            </details>
            <message>Changed too large number of Rooms To Sell to 254 for: 2023-10-25</message>
        </warning>
    </warnings>
</availability>
<!-- RUID: [UmFuZG9tSVetc] -->

Warnings will not prevent a request from processing. They merely point out unexpected or unadvisable behaviour. We recommend that you keep the number of warnings to zero.