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 the minimum time duration in advance until which guests are allowed to book a date. 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.
• MaxAdvancedBookingOffset: Refers to the maximum time duration in advance that guests are allowed to book a date. 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.

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

Mapping room types and rate plans

To map your room types and rate plans to Booking.com's, you should use the retrieving roomrates endpoint. You could also use the retrieving room types and retrieving rate plans endpoints, but these contain less complete information. You could still use either to troubleshoot issues with mapping as needed.

What is the maximum number of roomrates the API supports?

You can create a maximum of 400 active roomrates for a property.

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:

• Use the HotelDescriptiveContentNotif endpoint if you have implemented it.
• Tell the property to use their property page on the Booking.com extranet to create a policy there.

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:

   • Retrieving the property details: You need the HotelDescriptiveInfo endpoint to retrieve all the existing policies on the property level.
   • Retrieving the policies that are already assigned to existing roomrates.

   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:

   • Retrieving the property details: You need the HotelDescriptiveInfo endpoint to retrieve all the existing policies on the property level.
   • Retrieving the policies that are already assigned to existing roomrates.

   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:

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

The following is a response body example when the limit of 400 roomrates is reached:

<OTA_HotelProductNotifRS>
    <Errors>
        <Error Type="10" Code="733" Status="NotProcessed" ShortText="Limit 400 of number of Room/Rate combinations has reached for hotel 64231."/>
    </Errors>
</OTA_HotelProductNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUedwgregreg3/GEVjlG+mTXmB9OkyhGlAKEMxDhfrIcesvuhxkdje8uY] -->

Response body parameters

The following table describes the response elements:

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.

  → 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:

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:

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:

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:

Retrieving active roomrates

Booking.com provides the B.XML endpoint to retrieve active roomrates details. Note that the endpoint doesn't return roomrates that specify deactivated room type or rate plan.

Schema difference between the OTA and B.XML endpoint's response

The following table captures the high-level difference between the two endpoints' responses. However, this is not an exhaustive list.

Using the B.XML endpoint

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

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

You can:

• Retrieve the relevant room type and rate plan IDs.
• Query roomrate details with or without rewritten rate details.
• Retrieve additional response details like flexible children prices, if they are set.

You can also use this endpoint to retrieve policy override information for active roomrates. Remember to use Booking.com IDs while creating availability and not your internal IDs.

To resolve security issues and non-standard system behavior, the v1.1 roomrates endpoint supports the UTF-16 encoding algorithm.

Header parameter

Body parameters

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

Request body example 1

The following is a request body example:

<request>
   <hotel_id>8011855</hotel_id>
</request>

Request body example 2

The following request body example retrieves roomrates that have policy overrides defined:

<request>
    <hotel_id>8011855</hotel_id>
    <policy_override_start_date>2024-01-12</policy_override_start_date>
    <policy_override_end_date>2024-02-29</policy_override_end_date>
</request>

Response body example

The following is a successful response body example:

<?xml version='1.0' encoding='UTF-8'?>
<roomrates>
    <rooms>
        <room id="801185509" hotel_id="8011855" hotel_name="HillTop Hotel" room_name="Penthouse Apartment">
            <rates>
                <rate id="25278032" max_persons="7" policy="General" policy_id="341337682" rate_name="summer rate" fixed_occupancy="2">
                    <meal_plan meal_plan_code="10"/>
                    <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="62"/>
                            <policy_overrides>
                                <policy_override start_date="2024-01-16" end_date="2024-02-23" policy_code="12"/>
                            </policy_overrides>
                        </cancel_policy>
                        <guarantee_payment_policy>
                            <guarantee_payment policy_code="1" effective_from="after_reservation_is_made" required="1"/>
                            <policy_overrides>
                                <policy_override start_date="2024-01-16" end_date="2024-02-23" policy_code="after_reservation_is_made"/>
                            </policy_overrides>
                        </guarantee_payment_policy>
                    </policies>
                    <pricing type="RLO">
                        <occupancy persons="3" percentage="125.0" round="1"/>
                        <occupancy persons="4" additional="10.0" round="0"/>
                        <additional_guests>
                            <price type="child" additional_guest_number="0" from_age="0" to_age="3" age_bucket_id="1" percentage="50.0"/>
                            <price type="child" additional_guest_number="0" from_age="4" to_age="12" age_bucket_id="2" percentage="30.0"/>
                            <price type="child" additional_guest_number="0" from_age="13" to_age="17" age_bucket_id="3" percentage="20.0"/>
                        </additional_guests>
                    </pricing>
                </rate>
            </rates>
        </room>
        <room id="801185512" hotel_id="8011855" hotel_name="HillTop Hotel" room_name="Villa">
            <rates>
                <rate id="33298392" max_persons="5" policy="Special Conditions 3" policy_id="342592279" rate_name="winter break rates" is_child_rate="1">
                    <meal_plan meal_plan_code="12"/>
                    <policies>
                        <booking_rules/>
                        <cancel_policy>
                            <cancel_penalty policy_code="166"/>
                        </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="0"/>
                    <rate_relation follows_closed="3" follows_restrictions="1" follows_policygroup_id="1" follows_price="1" parent_rate_id="31105118" percentage="90.0"/>
                </rate>
            </rates>
        </room>
    </rooms>
</roomrates>
<!-- RUID: [f0020c39-f851-4e8d-cvd2q-98c9845a0940] -->

Response body parameters

The following table describes the response elements:

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

https://supply-xml.booking.com/hotels/ota/OTA_HotelProductNotif?HotelCode=123&IncludeReadOnly=1&OverridePolicyStart=2023-03-01&OverridePolicyEnd=2023-04-01&SupportRateRewrite=0

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelProductNotifRS>
    <HotelProducts HotelCode="1">
        <HotelProduct ReadOnly="true" ChildRate="true">
            <RoomTypes>
                <RoomType RoomTypeCode="2" MaxOccupancy="5" />
            </RoomTypes>
            <RatePlans>
                <RatePlan RatePlanCode="11" />
            </RatePlans>
            <ValueAddInclusions>
                <MealPlan MealPlanCode="0" />
            </ValueAddInclusions>
            <PolicyInfo>
                <BookingRules>
                    <BookingRule MinAdvancedBookingOffset="P10D" />
                    <BookingRule MaxAdvancedBookingOffset="P10D1H" />
                    <BookingRule ReleaseTimeOfDayStart="1" />
                    <BookingRule ReleaseTimeOfDayEnd="2" />
                </BookingRules>
                <CancelPolicy>
                    <CancelPenalty PolicyId="325235" PolicyName="general" PolicyCode="222" />
                    <TPA_Extensions>
                        <NoShowPolicy Penalty="default"/>
                    </TPA_Extensions>
                </CancelPolicy>
                <GuaranteePaymentPolicy>
                    <GuaranteePayment EffectiveFrom="after_cancellation_fee_begins" PrePaymentRequired="true" />
                </GuaranteePaymentPolicy>
                <OverridePolicies>
                    <OverridePolicy PolicyId="333" PolicyName="override1">
                        <BookDates>
                            <BookDate Start="2023-01-01" End="2023-01-02" />
                        </BookDates>
                    </OverridePolicy>
                    <OverridePolicy PolicyId="444" PolicyName="override2">
                        <BookDates>
                            <BookDate Start="2023-01-03" End="2023-01-04" />
                        </BookDates>
                    </OverridePolicy>
                </OverridePolicies>
            </PolicyInfo>
            <TPA_Extensions>
                <PricingType Value="RLO" Price1="false">
                    <Occupancy MaxAdultOccupancy="1" Round="true" Percent="25.9" />
                    <Occupancy MaxAdultOccupancy="2" Round="false" Amount="25.0" />
                </PricingType>
                <RateRelation FollowsRestrictions="true" Percent="55.2" FollowsPolicy="true" FollowsPrice="false" ParentRatePlanCode="12" FollowsClosed="2" />
            </TPA_Extensions>
            <AdditionalGuestAmounts>
                <AdditionalGuestAmount AdditionalGuestNumber="0" MinAge="0" AgeBucketID="1" Amount="10.0" MaxAge="3" AgeQualifyingCode="8" />
                <AdditionalGuestAmount AdditionalGuestNumber="1" MinAge="4" AgeBucketID="2" Percent="50.0" MaxAge="12" AgeQualifyingCode="8" />
            </AdditionalGuestAmounts>
        </HotelProduct>
    </HotelProducts>
</OTA_HotelProductNotifRS>
<!-- RUID: [Z104215yh9YeXU9U0vxS7qEshGUqEDsuqNgPguHj+W/wiXPORW30Rmu5Qyp2=] -->