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.

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.

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

Elements for creating a roomrate¶

Before creating a roomrate using the OTA_HotelProductNotif endpoint, you must have created the following resources.

Mandatory

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

Not mandatory but recommended to specify

• Policy ID: Assign a policy (combination of cancellation and prepayment terms) to a roomrate. To create a cancellation policy for the property, use the Policies API.

Note: If you do not specify a cancellation policy, the property's default policy is assigned to the roomrate. To identify the default policy of the property, look for <Tags><Default/></Tags> in the GET /policies response.

Optional

• Meal plan details: Indicate whether there is a meal plan and if so what that meal plan is.
• 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.

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.

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.

Body parameters¶

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

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

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

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

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:

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:

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 two endpoints to retrieve roomrates details using two different specifications:

• Using the OTA endpoint
• Using the B.XML endpoint

Difference between implementing the OTA vs B.XML endpoints¶

Booking.com provides the B.XML endpoint to retrieve roomrates details.

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 OTA endpoint¶

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

The GET OTA_HotelProductNotif request enables you to retrieve active roomrates for a property. You can retrieve the relevant room type and rate plan IDs. Remember to use Booking.com IDs while creating availability and not your internal IDs.

You can also use this endpoint to retrieve policy override information for active roomrates.

Query parameters¶

The following table describes the elements you can add in the query:

Query parameter example¶

The following is a query parameter example:

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

Response body example¶

The following is a successful response body example:

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

Response body parameters¶

The following table describes the response elements:

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: