Managing roomrates

A roomrate (also known as a product) is the unique combination of a room type and a rate plan with conditions. These conditions can consist of:

  • Policy: Refers to a combination of a cancellation and a prepayment policy.
  • Cancellation policy: Refers to whether there is and what the penalty is for a guest if they cancel a booking within a given time frame.
  • Prepayment policy: Refers to whether and when the property takes a prepayment from the guest.
  • Override policy: Refers to a policy that you can set on certain dates to overwrite the policy already assigned to a roomrate.
  • Booking restrictions: Refers to certain restrictions you can set when it comes to booking a roomrate.
  • Meal plan: Refers to whether there is and what the meal plan is assigned to the roomrate.

You need roomrates to create and push inventory (availability) and rates (prices).

Managing policies and restrictions

It is very important to properly understand what policies and restrictions are and how to assign them to roomrates in the context of the /ota/OTA_HotelProductNotif endpoint. Read this before you start creating roomrates.

What is a policy?

You must see a policy as a combination of a cancellation policy and a prepayment policy.

To find all the available cancellation codes, see cancellation policies. You can find free and non-free cancellations. Each one specifies the time frame in which a guest can cancel (with the exception of non-refundable with code 1) and what the possible penalty is for a guest if they cancel after a specific deadline or deadlines.

A policy can also include a prepayment. If prepayment is required, it further specifies whether the prepayment must happen after a guest makes a reservation (after_reservation_is_made) or when the guest can no longer cancel for free (after_cancellation_begins).

What is an override policy?

An override policy is just a policy. However, you use it to overwrite 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 and is not possible to book. You can set the following restrictions:

  • MinAdvancedBookingOffset: Refers to point in time until a roomrate is still bookable relative to the check-in. In other words, this specifies the moment from when a guest can no longer book the roomrate.
  • MaxAdvancedBookingOffset: Refers to point in time from when a roomrate becomes bookable relative to the check-in. In other words, this specifies the moment from when a guest can start booking the roomrate.

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. If you want to update a roomrate, you set ProductNotifType to Overlay.

Elements for creating a roomrate

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

  • Property id
  • Room type id
  • Rate plan id

To further expand a roomrate, it is recommended to also add:

  • Value add inclusions: To indicate whether there is a meal plan and if so what that meal plan is.
  • Policy: To assign an existing policy (combination of cancellation and prepayment) to a roomrate.

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. This means that if you want to create or update policies for a property, you must either:

How do you assign a policy?

To assign a policy to a roomrate, follow these steps:

  1. Retrieve the property's existing policies either by:

    You only need the cancellation policy code, because the prepayment policy is implicitly connected to this cancellation policy code. To know what each code represents, see the cancellation policies.

  2. Assign the policy by adding the code to the PolicyCode element (CancelPolicy > CancelPenalty > PolicyCode).

How do you assign an override policy?

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

  1. Retrieve the property's existing policies either by:

    For policy overrides, you need the policy name and not the policy code. If you use the HotelDescriptiveInfo endpoint, you can use the name under PolicyName (CancelPolicy > CancelPenalty > PolicyName). If you only retrieve policies that are already assigned to existing roomrates., you must look at the name under policy (room > rates > rate > policy) and find its policy override name equivalent in the following table:

    roomrate name policy override name
    General PTT_GENERAL
    Non-refundable PTT_NON_REFUNDABLE
    Special conditions PTT_SPECIAL_CONDITIONS
    Special conditions 2 PTT_SPECIAL_CONDITIONS_2
    Special conditions 3 PTT_SPECIAL_CONDITIONS_3
    Special conditions 4 PTT_SPECIAL_CONDITIONS_4
    Fully flexible PTT_FULLY_FlEXIBLE
  2. Assign the policy by adding the policy override name to the PolicyName element (OverridePolicies > OverridePolicy > PolicyName).

→ To know what each policy name represents, find the policy code and see the cancellation policies.

Body parameters

The following table describes what 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 and booking policy objects. object optional
>>>> CancelPolicy Contains the CancelPenalty objects. object optional
>>>>> CancelPenalty Contains the policy information. object optional
PolicyCode Specifies the policy (cancellation and prepayment policy combination) you assign to the roomrate. integer optional To see the list of cancellation and prepaymeny policy codes at Booking.com, see cancellation and prepayment polices.
>>>> 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
PolicyName Specifies the name of the override policy. string 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 tpye can start being booked. integer optional This follows time intervals of 15 minutes starting at midnight. So 41 equals 10.15AM.
ReleaseTimeOfDayEnd Specifies the time of the day the room tpye can no longer be booked. integer optional This follows time intervals of 15 minutes starting at midnight. So 80 equals 08.00PM.

Request body example

The following is a request body example:

<OTA_HotelProductNotifRQ>
  <HotelProducts HotelCode="64231">
    <HotelProduct ProductNotifType="New">
      <RoomTypes>
        <RoomType RoomTypeCode="6423112" />
      </RoomTypes>
      <RatePlans>
        <RatePlan RatePlanCode="12483478" />
      </RatePlans>
      <ValueAddInclusions>
        <MealPlan MealPlanCode="19" />
      </ValueAddInclusions>
      <PolicyInfo>
        <BookingRules>
          <BookingRule MinAdvancedBookingOffset="P1D" />
          <BookingRule MaxAdvancedBookingOffset="P14D" />
        </BookingRules>
        <CancelPolicy>
          <CancelPenalty PolicyCode="15"/>
        </CancelPolicy>
        <OverridePolicies>
          <OverridePolicy PolicyName="PTT_NON_REFUNDABLE">
            <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"/>
              <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, it is very important to do the following:

  • Set InvNotifType to Overlay.
  • Include all existing information: This means you send the roomrate information as if you create a new roomrate, changing the elements you want to update.
    → To retrieve most of your roomrate information, see [retrieving roomrates.][retrieve-active-roomrates]

→ To retrieve the policy names in the same way as you created them, see the CancelPolicy elements when retrieving property details.

Requirements for updating a roomrate

To create 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 what 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 and booking policy objects. object optional
>>>> CancelPolicy Contains the CancelPenalty objects. object optional
>>>>> CancelPenalty Contains the policy information. object optional
PolicyCode Specifies the policy (cancellation and prepayment policy combination) you assign to the roomrate. integer optional To see the list of cancellation and prepaymeny policy codes at Booking.com, see cancellation and prepayment polices.
>>>> 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
PolicyName Specifies the name of the override policy. string 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 tpye can start being booked. integer optional This follows time intervals of 15 minutes starting at midnight. So 41 equals 10.15AM.
ReleaseTimeOfDayEnd Specifies the time of the day the room tpye can no longer be booked. integer optional This follows time intervals of 15 minutes starting at midnight. So 80 equals 08.00PM.

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 PolicyCode="15" />
        </CancelPolicy>
        <OverridePolicies>
          <OverridePolicy PolicyName="PTT_NON_REFUNDABLE">
            <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 what 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
RatePlanCode Specifies the rate plan id. integer required
>>> RatePlans Contains a RatePlan object. object required
>>>> RatePlan Contains the rate plan information. object 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 what 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 you want to retrieve the active rate plans for. 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="6423112"
        hotel_id="12483478"
        hotel_name="Best Hotel"
        max_children="2"
        room_name="Double Room">
    <rates>
      <rate id="2323232"
            max_persons="3"
            policy="General"
            policy_id="30"
            rate_name="Standard Rate" />
      <rate id="4545454"
            max_persons="3"
            policy="Non-Refundable"
            policy_id="1"
            rate_name="Non-Refundable Rate" />
    </rates>
  </room>
  ...
</rooms>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUPwiuucSHwvOzUg7go2d23fvRzq/WYNpZcFinFyrhAIH9Bw+Rgsf2Km] -->

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
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.