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¶

POST
https://supply-xml.booking.com/hotels/xml/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.
Close a room type on a specified date. Even if roomrates are open, the room type is not available for booking.
Update for periods in the future and up to one day in the past, in the Central European Time (CET) timezone.
Make past date updates up to 1 day in the past (follows Central European Time (CET) timezone). Updates more than 1 day in the past returns a NOT_A_VALID_DATE error.
See improved error handling and error description.

Setting availability for child rates¶

While setting up availability using rate IDs that are configured as child rates, make sure the request doesn't set values for fields that are configured to inherit from the parent rate plan. For example, if you try to set a value for min_advance_res restrictions for a child rate while the child rate is configured to follow restrictions or set price when FollowsPrice is set, the API returns a partial success response with an error. To resolve the error, specify a rate plan ID that is either configured as a parent rate, or a child rate that does not have the following restrictions: FollowsPrice, or FollowsRestrictions.

Similar to the v1.0 behaviour, the above constraint does not apply to the FollowsClosed restriction. While creating availability using a child rate ID, you can update the status of the room type to open or close, irrespective of the value set in FollowsClosed. However, if an availability is set using a parent rate along with open/close information, then the room type status for the associated child rate is also updated. To reiterate, there is no change to the FollowsClosed restriction behaviour.

For a complete list of new and changed error codes, see Troubleshooting B.XML availability error responses.

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	Currently supports the version 1.1 (default). Version 1.0 is deprecated. If used, the endpoint returns a 406 Not acceptable error.

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¶

This section contains examples of successful and unsuccessful responses. For a detailed description of all possible errors and warnings, see the Troubleshooting B.XML availability error 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¶

For a detailed description of all possible errors and warnings, see the Troubleshooting B.XML availability error responses.

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.

Is this page helpful? Yes | No