Managing roomrates

A roomrate is a unique combination of room type, rate plan and conditions. Creating a roomrate helps in creating inventory (availability) and rates (prices) later.

Before creating a roomrate, make sure to create a room type using the OTA_HotelInvNotif endpoint and a rate plan using the OTA_HotelRatePlanNotif endpoint.

You can also specify conditions while creating a roomrate, such as:

  • Cancellation policy: A cancellation policy is a combination of payment rules, which consists of cancellation, prepayment (also known as guarantee payment) and/or no show rules that is enforced when guests make a reservation. Each payment rule defines how much (in percentage of the total booking price or in nights) and when a guest is charged in case of cancellation or no-show.
  • Override policy: A cancellation policy that you can set on certain dates to override the policy already assigned to a roomrate.
  • Booking restrictions: Restrictions such as how far in advance should guests book a reservation for the roomrate to be activated.
  • Meal plan: A meal plan that is assigned to the roomrate.

Specifying cancellation policy and restrictions

When creating a roomrate, you can specify a cancellation policy that is already created on the property level. If you do not specify a policy, the /ota/OTA_HotelProductNotif endpoint assigns the default policy to the roomrate.

To create and manage policies, use the Policies API. When assigning a policy to a roomrate, you must specify the policy ID.

Policies API is currently in Beta

Note that the Policies API is currently in beta. Make sure to direct any questions during the beta phase to your Booking.com contact person via the appropriate channels.

What is an override policy?

An override policy is a regular cancellation policy that you can use to override the main policy of a roomrate for a specified date range.

Let's say a property uses a flexible policy for most of the year, but they want to use a non-refundable policy for their peak season. That would be a good use case for a policy override.

What are restrictions?

Restrictions enable you to specify when a roomrate with a specific policy is available to book. You can set the following restrictions:

  • MinAdvancedBookingOffset: Specify the closest available time (year, month, day, hours) until a guest can book a room type relative to their check-in time. In other words, this specifies the moment from when a guest can no longer book the roomrate. The search date is counted as one of the days in the restriction length. For example, if you specify P2D, then the guests cannot specify the next day as a check-in start date.
  • MaxAdvancedBookingOffset: Specify the maximum time (year, month, day, hours) available in advance to book a room type relative to the check-in time. In other words, this specifies the moment from when a guest can start booking the roomrate. The search date is counted as one of the days in the restriction length. For example, if you specify P2D, then the guests can only book for stays that occur 2 or fewer days relative to the search date.

You can also set the specific hours in which a roomrate is available per day, but this is not recommended.

Creating a roomrate

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelProductNotif

The POST /ota/OTA_HotelProductNotif request enables you to create roomrates for your property.

Creating or updating

To create a roomrate you set ProductNotifType to New. Whereas, to update a roomrate, you set ProductNotifType to Overlay.

Elements for creating a roomrate

To create a roomrate on Booking.com, the following elements are required:

  • Property ID
  • Room type ID - To create a room type using the OTA_HotelInvNotif endpoint, see Creating room types.
  • Rate plan ID - To create a rate plan using the OTA_HotelRatePlanNotif endpoint, see Creating rate plans.

You can also specify:

  • Cancellation policy: Assign a policy (combination of cancellation and prepayment terms) to a roomrate.
  • Meal plan details: Indicate whether there is a meal plan and if so what that meal plan is.

The following elements are optional:

  • Override policy
  • Booking rules

Assigning policies to roomrates

You can only assign existing policies using the /ota/OTA_HotelProductNotif endpoint. That is, policies that were already created for the property.

Specify Policy ID

When assigning a policy to a roomrate, you must specify the policy ID.

To create or update policies for a property, you must:

  • Use the Policies API, or
  • Request the property to use their property page on the Booking.com extranet to create a policy.

To assign a policy while creating a roomrate, follow these steps:

  1. Retrieve the property's existing policies and choose a policy to assign to a roomrate. Make sure to note the policy ID for the relevant policy. You can assign the same policy to many roomrates.
    [Optional] If the property does not contain a policy with a suitable cancellation penalty, you can create a policy for the property with an appropriate cancellation code. To know more about all the available cancellation codes, see the cancellation policy codes.
  2. Assign the policy by specifying the policy ID.

Roomrate always has a policy assigned

Whenever you create a roomrate, you must either specify a policy to be assigned to the roomrate or the API assigns the default policy to the roomrate. You cannot unassign a policy. You must either reassign a different policy to the roomrate by updating the roomrate or change the policy details that is already assigned to the roomrate.

Assigning an override policy

Assigning an override policy is similar to assigning a policy to a roomrate.

To assign an override policy to a room rate, follow these steps:

  1. Retrieve the property's existing policies and choose a policy to assign to a roomrate.
  2. Assign the overriding policy by specifying the policy ID.

Default policy assignment

If the policy ID is not supplied while creating the room rate, the API assigns the default policy to the roomrate. To identify the default policy, check for the Default tag in the GET /policies response.

Body parameters

The following table describes the elements you must add in the request body:

Element Attribute Description Type Required/Optional Notes
OTA_HotelProductNotifRQ Contains the HotelProducts array. object required
> HotelProducts Contains the HotelProduct objects. array required
HotelCode Specifies the unique ID of the property you create roomrates for. integer required
>> HotelProduct Contains the roomrate information. object required
ProductNotifType Specifies whether the request is to create a roomrate (New) or modify an existing one (Overlay). enum required Possible values are New and Overlay. You must use New to create a roomrate.
>>> RoomTypes Contains a RoomType object. object required
>>>> RoomType Contains the room type information. object required
RoomTypeCode Specifies the room type ID. integer required
>>> RatePlans Contains a RatePlan object. object required
>>>> RatePlan Contains the rate plan information. object required
RatePlanCode Specifies the rate plan ID. integer required
>>> ValueAddInclusions Contains a MealPlan object. object optional
>>>> MealPlan Contains the meal plan information. object optional If you do not include this element, the default is no meal plan included.
MealPlanCode Specifies the meal plan ID. integer optional To see the list of meal plan codes at Booking.com, see meal plan codes.
>>> PolicyInfo Contains the cancellation policy details. object optional
>>>> CancelPolicy Contains the CancelPenalty object. object optional
>>>>> CancelPenalty Contains the policy information. object optional
PolicyId Specifies the policy ID to assign to the roomrate. The ID must belong to one of the policies created for the property. To get a list of all the policies created for a property, see get-policy-details. integer optional If this parameter is not specified, the default policy is assigned to the roomrate. You can identify the default policy with the <Tags><Default/></Tags> in the GET /policies response.
>>>> OverridePolicies Contains the OverridePolicy objects. object optional
>>>>> OverridePolicy Contains the override policy information, which overwrites other policies set for this roomrate on the dates specified within the object. object optional
PolicyId Specifies the ID of the override policy. integer optional
>>>>>> BookDates Contains the BookDate objects. object optional
>>>>>>> BookDate Contains the book date information, which specify the dates when the override policy overwrites other policies. object optional
Start Specifies the start date of the override policy. string optional Format is in YYYY-MM-DD.
End Specifies the end date of the override policy. string optional Format is in YYYY-MM-DD.
>>>>>> ActiveWeekdays Contains the ActiveWeekDay objects. object optional
>>>>>>> ActiveWeekday Contains the active week day information, which specify the days when the override policy overwrites other policies. object optional
Day Specifies the name of the day of the week. string optional Possible values are: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday.
>>>> BookingRules Contains the BookingRule objects. object optional
>>>>> BookingRule Contains the booking policy information. object optional
MinimumAdvancedBookingOffset Specifies the minimum amount of time in which a room type must be booked relative to midnight (24:00 CE(S)T) of the check-in date start. string optional This is the format used: P[0-9]+(Y,M,D,H). An example is: P5H means the room must be booked before 19:00 on the day before the check-in date.
MaximumAdvancedBookingOffset Specifies the maximum amount of time in which a room type can be booked relative to midnight (24:00 CE(S)T) of the check-in date start. string optional This is the format used: P[0-9]+(Y,M,D,H). An example is: P14D means the room can be booked a maximum of 14 days before the check-in date.
ReleaseTimeOfDayStart Specifies the time of the day the room type can start being booked. HH:MM optional This allows time intervals of 15 minutes starting at midnight. For example: 10:15.
ReleaseTimeOfDayEnd Specifies the time of the day the room type can no longer be booked. HH:MM optional This allows time intervals of 15 minutes starting at midnight. For example: 18:00.

Request body example

The following is a request body example:

<OTA_HotelProductNotifRQ>
    <HotelProducts HotelCode="8011855">
        <HotelProduct ProductNotifType="New">
            <RoomTypes>
                <RoomType RoomTypeCode="801185502" />
            </RoomTypes>
            <RatePlans>
                <RatePlan RatePlanCode="12483478" />
            </RatePlans>
            <ValueAddInclusions>
                <MealPlan MealPlanCode="19" />
            </ValueAddInclusions>
            <PolicyInfo>
                <BookingRules>
                    <BookingRule MinAdvancedBookingOffset="P1D" />
                    <BookingRule MaxAdvancedBookingOffset="P14D" />
                </BookingRules>
                <CancelPolicy>
                    <CancelPenalty PolicyId="342546377"/>
                </CancelPolicy>
                <OverridePolicies>
                    <OverridePolicy  PolicyId="342546364">
                        <BookDates>
                            <BookDate Start="2022-06-06" End="2022-06-29"/>
                            <BookDate Start="2022-07-06" End="2022-07-29"/>
                        </BookDates>
                        <ActiveWeekdays>
                            <ActiveWeekday Day="Friday"/>
                            <ActiveWeekday Day="Saturday"/>
                            <ActiveWeekday Day="Sunday"/>
                        </ActiveWeekdays>
                    </OverridePolicy>
                </OverridePolicies>
            </PolicyInfo>
        </HotelProduct>
    </HotelProducts>
</OTA_HotelProductNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelProductNotifRS>
  <Success />
</OTA_HotelProductNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUedwgregreg3/GEVjlG+mTXmB9OkyhGlAKEMxDhfrI] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelProductNotifRS Contains the response data. object
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Updating a roomrate

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelProductNotif

The POST /ota/OTA_HotelProductNotif request enables you to update roomrates for your property.

When updating a roomrate, make sure to:

  • Set InvNotifType to Overlay.
  • Include all existing information: Make sure to specify all existing details of the roomrate. Your update request should look similar to the request you used to create the roomrate, except for the elements you want to update.

Policy overrides are full overlays

When editing policy overrides make sure to specify all existing overrides, including overrides for future dates, on every update.

→ To retrieve the roomrate information, see retrieving roomrates.

→ To retrieve the policy details, see Retrieve the property's existing policies.

Requirements for updating a roomrate

To update a roomrate on Booking.com, the following basic elements are required:

  • Property ID
  • Room type ID
  • Rate plan ID

Body parameters

The following table describes the elements you must add in the request body:

Element Attribute Description Type Required/Optional Notes
OTA_HotelProductNotifRQ Contains the HotelProducts array. object required
> HotelProducts Contains the HotelProduct objects. array required
HotelCode Specifies the unique ID of the property you create roomrates for. integer required
>> HotelProduct Contains the roomrate information. object required
ProductNotifType Specifies whether the request is to create a roomrate (New) or modify an existing one (Overlay). enum required Possible values are New and Overlay. You must use New to create a roomrate.
>>> RoomTypes Contains a RoomType object. object required
>>>> RoomType Contains the room type information. object required
RoomTypeCode Specifies the room type ID. integer required
>>> RatePlans Contains a RatePlan object. object required
>>>> RatePlan Contains the rate plan information. object required
RatePlanCode Specifies the rate plan ID. integer required
>>> ValueAddInclusions Contains a MealPlan object. object optional
>>>> MealPlan Contains the meal plan information. object optional If you do not include this element, the default is no meal plan included.
MealPlanCode Specifies the meal plan ID. integer optional To see the list of meal plan codes at Booking.com, see meal plan codes.
>>> PolicyInfo Contains the cancellation policy details. object optional
>>>> CancelPolicy Contains the CancelPenalty object. object optional
>>>>> CancelPenalty Contains the policy information. object optional
PolicyId Specifies the policy ID to assign to the roomrate. The ID must belong to one of the policies created for the property. To get a list of all the policies created for a property, see get-policy-details. integer optional If this parameter is not specified, the default policy is assigned to the roomrate. You can identify the default policy with the <Tags><Default/></Tags> in the GET /policies response.
>>>> OverridePolicies Contains the OverridePolicy objects. object optional
>>>>> OverridePolicy Contains the override policy information, which overwrites other policies set for this roomrate on the dates specified within the object. object optional
PolicyId Specifies the ID of the override policy. integer optional
>>>>>> BookDates Contains the BookDate objects. object optional
>>>>>>> BookDate Contains the book date information, which specify the dates when the override policy overwrites other policies. object optional
Start Specifies the start date of the override policy. string optional Format is in YYYY-MM-DD.
End Specifies the end date of the override policy. string optional Format is in YYYY-MM-DD.
>>>>>> ActiveWeekdays Contains the ActiveWeekDay objects. object optional
>>>>>>> ActiveWeekday Contains the active week day information, which specify the days when the override policy overwrites other policies. object optional
Day Specifies the name of the day of the week. string optional Possible values are: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday.
>>>> BookingRules Contains the BookingRule objects. object optional
>>>>> BookingRule Contains the booking policy information. object optional
MinimumAdvancedBookingOffset Specifies the minimum amount of time in which a room type must be booked relative to midnight (24:00 CE(S)T) of the check-in date start. string optional This is the format used: P[0-9]+(Y,M,D,H). An example is: P5H means the room must be booked before 19:00 on the day before the check-in date.
MaximumAdvancedBookingOffset Specifies the maximum amount of time in which a room type can be booked relative to midnight (24:00 CE(S)T) of the check-in date start. string optional This is the format used: P[0-9]+(Y,M,D,H). An example is: P14D means the room can be booked a maximum of 14 days before the check-in date.
ReleaseTimeOfDayStart Specifies the time of the day the room type can start being booked. HH:MM optional This allows time intervals of 15 minutes starting at midnight. For example: 10:15.
ReleaseTimeOfDayEnd Specifies the time of the day the room type can no longer be booked. HH:MM optional This allows time intervals of 15 minutes starting at midnight. For example: 18:00.

Request body example

The following is a request body example:

<OTA_HotelProductNotifRQ>
    <HotelProducts HotelCode="64231">
        <HotelProduct ProductNotifType="Overlay">
            <RoomTypes>
                <RoomType RoomTypeCode="6423112" />
            </RoomTypes>
            <RatePlans>
                <RatePlan RatePlanCode="12483478" />
            </RatePlans>
            <ValueAddInclusions>
                <MealPlan MealPlanCode="0" />
            </ValueAddInclusions>
            <PolicyInfo>
                <BookingRules>
                    <BookingRule MinAdvancedBookingOffset="P1D" />
                    <BookingRule MaxAdvancedBookingOffset="P14D" />
                </BookingRules>
                <CancelPolicy>
                    <CancelPenalty PolicyId="350338154" />
                </CancelPolicy>
                <OverridePolicies>
                    <OverridePolicy PolicyId="341337684">
                        <BookDates>
                            <BookDate Start="2021-06-06" End="2021-06-29"/>
                            <BookDate Start="2021-07-06" End="2021-07-29"/>
                        </BookDates>
                        <ActiveWeekdays>
                            <ActiveWeekday Day="Friday"/>
                            <ActiveWeekday Day="Saturday"/>
                        </ActiveWeekdays>
                    </OverridePolicy>
                </OverridePolicies>
            </PolicyInfo>
        </HotelProduct>
    </HotelProducts>
</OTA_HotelProductNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelProductNotifRS>
  <Success />
</OTA_HotelProductNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUedwgregreg3/GEVjlG+mTXmB9Owf2f+Kq=Mzyiykpi6Yx5oKzRKEMxDhfrI] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelProductNotifRS Contains the response data. object
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Removing roomrates

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelProductNotif

The POST /ota/OTA_HotelProductNotif request enables you to remove a roomrate by disconnecting the room type and rate plan.

Requirements for removing a roomrate

To remove a roomrate from Booking.com, you only need the following elements:

  • Property id
  • Room type id
  • Rate plan id

You must also set ProductNotifType to Remove.

Body parameters

The following table describes the elements you must add in the request body:

Element Attribute Description Type Required/Optional Notes
OTA_HotelProductNotifRQ Contains the HotelProducts array. object required
> HotelProducts Contains the HotelProduct objects. array required
HotelCode Specifies the unique ID of the property you create roomrates for. integer required
>> HotelProduct Contains the roomrate information. object required
ProductNotifType Specifies whether the request is to remove a roomrate. enum required Value to remove a roomrate is remove.
>>> RoomTypes Contains a RoomType object. object required
>>>> RoomType Contains the room type information. object required
RoomTypeCode Specifies the room type id. integer required
>>> RatePlans Contains a RatePlan object. object required
>>>> RatePlan Contains the rate plan information. object required
RatePlanCode Specifies the rate plan id. integer required

Request body example

The following is a request body example:

<OTA_HotelProductNotifRQ>
  <HotelProducts HotelCode="64231">
    <HotelProduct ProductNotifType="Remove">
      <RoomTypes>
        <RoomType RoomTypeCode="6423112" />
      </RoomTypes>
      <RatePlans>
        <RatePlan RatePlanCode="12483478" />
      </RatePlans>
    </HotelProduct>
  </HotelProducts>
</OTA_HotelProductNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelProductNotifRS>
  <Success />
</OTA_HotelProductNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUedwgregreg3/GcBkCkoW0/uhiPmwiL6pcbMzyiykpi6Yx5oKzRKEMxDhfrI] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelProductNotifRS Contains the response data. object
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Retrieving active roomrates

POST
https://supply-xml.booking.com/hotels/xml/roomrates

The POST /xml/roomrates request enables you to retrieve active roomrates for a property.

Body parameters

The following table describes the elements you must add in the request body:

Element Description Type Required/Optional Notes
request Contains the request information. object required
> hotel_id Specifies the unique ID of the property for which you want to retrieve the active rate plans. integer required

Request body example

The following is a request body example:

<request>
   <hotel_id>6314570</hotel_id>
</request>

Response body example

The following is a successful response body example:

<rooms>
    <room id="801185504" hotel_id="8011855" hotel_name="HillTop Hotel" max_children="0" room_name="Quadruple Room">
        <rates>
            <rate id="25279855" max_persons="4" policy="General" policy_id="341337682" rate_name="summer time rate">
                <meal_plan meal_plan_code="19"/>
                <policies>
                    <booking_rules>
                        <booking_rule min_advanced_booking_offset="P1D"/>
                        <booking_rule max_advanced_booking_offset="P14D"/>
                    </booking_rules>
                    <cancel_policy>
                        <cancel_penalty policy_code="43"/>
                    </cancel_policy>
                    <guarantee_payment_policy>
                        <guarantee_payment policy_code="166" effective_from="after_reservation_is_made" required="1"/>
                    </guarantee_payment_policy>
                </policies>
                <pricing type="Standard" price1="1"/>
            </rate>
            <rate id="25278032" max_persons="4" policy="General" policy_id="341337682" rate_name="off season rate">
                <meal_plan meal_plan_code="19"/>
                <policies>
                    <booking_rules/>
                    <cancel_policy>
                        <cancel_penalty policy_code="43"/>
                    </cancel_policy>
                    <guarantee_payment_policy>
                        <guarantee_payment policy_code="166" effective_from="after_reservation_is_made" required="1"/>
                    </guarantee_payment_policy>
                </policies>
                <pricing type="Standard" price1="1"/>
            </rate>
        </rates>
    </room>
</rooms>
        <!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWY/m9qZeSpAMF1P4MPaHT4YuVomrqi658TiuVkBqY769z9Ccvkm+8R2JHVfWcuDJYFRGTMUVZxY] --

Response body parameters

The following table describes the response elements:

Element Attribute Description Type Notes
rooms Contains the room objects. object
> room Contains the room type information. object
id Specifies the unique Booking.com ID of the room type. integer
hotel_id Specifies the unique ID of the property. integer
hotel_name Specifies the name of the property. string
max_children Specifies the maximum number of children allowed in the room type. integer
room_name Specifies the name of the room type. string
>> rates Contains the rate objects. object
>>> rate Contains the rate plan information. object
id Specifies the unique Booking.com ID of the rate plan. integer
max_persons Specifies the maximum number of adults allowed in the room type. integer
policy Specifies the name of the policy. string
policy_id Specifies the unique ID of the policy. integer
rate_name Specifies the name of the rate plan. string
>>>> meal_plan Contains the meal plan information. object
meal_plan_code Specifies the meal plan ID. integer To see the list of meal plan codes at Booking.com, see meal plan codes.
>>>> policies Contains the cancellation policy details. object
>>>>> booking_rules Contains the BookingRule objects. object
>>>>>> booking_rule Contains the booking policy information. object
min_advanced_booking_offset Specifies the minimum amount of time in which a room type must be booked relative to midnight (24:00 CE(S)T) of the check-in date start. string This is the format used: P[0-9]+(Y,M,D,H). An example is: P5H means the room must be booked before 19:00 on the day before the check-in date.
max_advanced_booking_offset Specifies the maximum amount of time in which a room type can be booked relative to midnight (24:00 CE(S)T) of the check-in date start. string This is the format used: P[0-9]+(Y,M,D,H). An example is: P14D means the room can be booked a maximum of 14 days before the check-in date.
>>>> cancel_policy Contains the CancelPenalty object. object
>>>>> cancel_penalty Contains the policy information. object
policy_code Specifies the cancellation policy code. integer For a full list of all the available cancellation codes, see the cancellation policy codes.
>>>> guarantee_payment_policy Contains the guarantee payment details. object
>>>>> guarantee_payment Contains the guarantee payment details. object
policy_code Specifies the cancellation policy code that has the guarantee payment details. integer For a full list of all the available cancellation codes, see the cancellation policy codes.
effective_from Specifies when the guarantee payment is charged. enumerated string Possible values are:
- after_reservation_is_made - Enforces guests to make a payment immediately after reservation.
- after_free_cancellation_ends: Enforces guests to make a payment after the free cancellation window has closed.
required Specifies whether a guarantee payment is mandatory. boolean Possible values are:
- 1: Guarantee payment required
- 0: Guarantee payment is not required
>>>> pricing Contains the pricing details. object
type Specifies the pricing type. string
price1 Specifies the price. integer
>>>>> occupancy Contains the occupancy details. object
persons Specifies the number of occupants. integer
percantage Specifies the percentage. integer
round Specifies the number of digits to round off. integer
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.