roomrates (B.XML)

The rooms, rates, and roomrates requests are used to map rooms and rates of hotels active on Booking.com. The roomrates, however, should be the preferred call and always be used as it should contain all information necessary in order to map. roomrates returns a list of room/rate/policy information needs to be pulled from the Booking.com systems. The room and rate IDs on Booking.com are the only way to identify the rooms and rates in the system. It is not possible to use a provider's own internal room and rate codes to send Inventory, Rates, and Restrictions on Booking.com.

Step 1: Request for room/rate/policy information

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

Request — HTTP Message Body Model

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <username>providermachinelogin</username>
  <password>********</password>
  <hotel_id>111111</hotel_id>

  <!-- optional -->
  <show_rates_status>2</show_rates_status>
</request>

Request — Node Overview

Node Name Nest Level Parent Node Value Range Data Type Node Multiplicity
hotel_id L1 request @5-7 digits integer 0..1
password L1 request -- string 1
request L0 NULL(root) -- -- 1
username L1 request -- string 1
show_rates_status L1 request 0,1,2,3,4,5 integer 0..1
  • The request body consists of a request root node. This is the parent node to the required username and password nodes, and the optional hotel_id node.

  • The child node username should contain the provider's Booking.com XML machine login.

  • The child node password should contain the provider's Booking.com XML machine password.

  • The optional child node hotel_id contains the Booking.com hotel id for which the provider wishes to check details for mapping. When the hotel_id is omitted, a complete list of room/rate/policy information for every property connected to the machine account in use will be generated.

  • The optional child node show_rates_status defines how the active status of rates is shown:

show_rates_status code Description
0 show All rates for this Room(default behaviour)
1 show only Active rates for this Room
2 show All rates for this Room and include @active attribute in the output
3 show only Inactive rates for this Room
4 show only Active rates for this Room and include @active attribute in the output
5 show only Inactive rates for this Room and include @active attribute in the output

Step 2: Response of available room/rate/policy information

Type HTTP Method Message Sender Message Receiver
Response POST Booking.com Connectivity Partner

Response — HTTP Message Body Sample

<rooms>
  <room id="11111101"
        hotel_id="111111"
        hotel_name="Fake Hotel"
        max_children="0"
        room_name="Single Room">
    <rates>
      <rate id="2323232"
            max_persons="1"
            policy="General"
            policy_id="99999999"
            rate_name="Standard Rate" />
      <rate id="4545454"
            max_persons="1"
            policy="Non-Refundable"
            policy_id="88888888"
            rate_name="Non-Refundable Rate" />
      <rate id="6767676"
            max_persons="1"
            policy="General"
            policy_id="99999999"
            rate_name="Special Rate"
            is_child_rate="1"
            readonly="1" />
    </rates>
  </room>
  <room id="11111102"
        hotel_id="111111"
        hotel_name="Fake Hotel"
        max_children="0"
        room_name="Double Room"
        readonly="1">
    <rates>
      <rate id="2323232"
            max_persons="2"
            policy="General"
            policy_id="99999999"
            rate_name="Standard Rate"/>
      <rate id="4545454"
            max_persons="2"
            policy="Non-Refundable"
            policy_id="88888888"
            rate_name="Non-Refundable Rate" 
            is_child_rate="1"/>
      <rate id="6767676"
            max_persons="2"
            policy="General"
            policy_id="99999999"
            rate_name="Special Rate"
            readonly="1" />
    </rates>
  </room>
</rooms>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXX==] -->

Response — Node Overview

Node Name Nest Level Parent Node Value Range Data Type Node Multiplicity
occupancies L4 rate 0..@max_persons integer 0..X
rate L3 rates -- -- 0..X
rates L2 room -- -- 0..1
room L1 rooms -- -- 0..X
rooms L0 NULL(root) -- -- 1
  • The response body consists of a rooms root element. This is the parent node of the room node(s).
  • The child room node contains the following attributes: @hotel_id, @hotel_name, @id, @max_children, @name, and @room_name, and is parent node to the rates node.
  • The grandchild rates node contains the individual rate node(s) associated with the given room node.
  • The great-grandchild rate node contains the @id, @max_persons, @name, @policy, @policy_id, @rate_name, as well as the optional attributes (when flagged) of @fixed_occupancy, @readonly and @is_child_rate as described below.
  • The optional great-great-grandchild node occupancies gives the possible guest counts for which pricing maybe set as specified on an accommodation with occupancy based pricing. Should the node exist and read "0", the tag can be ignored and the Standard Pricing Model is assumed (eg. send the price for single use and max occupancy prices for the room if no @fixed_occupancy specified).

Response — Attribute(@) Overview

Attribute Name Node Name Value Range Data Type Node Multiplicity
@active rate 0,1 boolean 0..1
@fixed_occupancy rate 1..@max_persons integer 0..1
@hotel_id room ~5-7 digits integer 1
@hotel_name room -- string 1
@id rate -- integer 1
@id room ~7-9 digits integer 1
@max_children room 0..X integer 1
@max_persons rate 1..X integer 1
@name rate -- string 1
@name room -- string 1
@policy rate -- string 1
@policy_id rate -- integer 1
@rate_name rate -- string 1
@readonly rate 0,1 boolean 0..1
@is_child_rate rate 0,1 boolean 0..1
@readonly room 0,1 boolean 0..1
@room_name room -- string 1
  • If @active="1", the rate is active and @active="0" implies inactive rate.
  • If @fixed_occupancy of the rate node is present, this indicates that the rate is configured to a Fixed Occupancy Model and prices should be pushed to Booking.com on this specific rate at this specified occupancy. For example, if set to '3', the provider should push only the rate for three persons for the given @id rate. 'Occupancy'/'persons' on Booking.com is only related to the number of adult guests. See also @max_persons of the rate node below.
  • The @hotel_id of the room node indicates the Booking.com accommodation id for the given room.
  • The @hotel_name of the room node indicates the Booking.com accommodation name for the given room.
  • The @id of the rate node indicates the Booking.com rate ID, which is to be used in combination with the @id of the room node for mapping by the provider.
  • The @id of the room node indicates the Booking.com room ID, which is to be used in combination with the @id of the rate node for mapping by the provider.
  • The @max_children of the room node indicates the maximum number of children allowed in the room as configured on Booking.com in addition to the max_persons (adults) of the rate. It is assumed that the any child rate nodes that fall under the given room node will allow up to this number of children for the prices pushed to Booking.com.
  • The @max_persons of the rate node indicates the maximum number of guests for which a Booking.com reservation could be made for the give rate ID. Example: If @fixed_occupancy is '2' and @max_persons is '4', the provider should push only the rate for two adult guests to Booking.com, but expect the reservations to come as any occupancy between 1-4.
  • The @name of the rate node indicates the Booking.com rate name for the given rate.
  • The @name of the room node indicates the Booking.com room name for the given room.
  • The @policy of the rate node indicates the Booking.com policy name for the given rate.
  • The @policy_id of the rate node indicates the Booking.com policy ID for the given rate.
  • The @rate_name of the rate node indicates the Booking.com rate name for the given rate.
  • If the @readonly of the rate node is set to '1', this means that the Connectivity Partner cannot push pricing to Booking.com for the specified rate and does not need to be mapped for rate updates. However, if the Provider handles reservations, this rate still needs to be mapped for reservations (@readonly enabled is also known as 'XMLRes' or 'XML reservations' only).
  • If the @is_child_rate of the rate node is set to '1', This means that this is a child rate. It will follow its parent rate according to the settings you set. Child rates can follow prices, restrictions, properties and policies of their parent rate.
  • If the @readonly of the room node is set to '1', this means that the Connectivity Partner should not push availability to Booking.com for the specified room nor pricing/restrictions for its rates, as it is expected that the accommodation will be managing information associated with this room via extranet.
  • The @room_name of the room node indicates the Booking.com room name for the given room.

As with every standard Booking.com response, an RUID string terminates the message inside an XML comment node and should be stored by the Connectivity Partner for at least 30 days.

Example Outputs of <show_rates_status>

If <show_rates_status> 0 </show_rates_status> (default, show all rates):

<rooms>
  <room id="11111101"
        hotel_id="111111"
        hotel_name="Fake Hotel"
        max_children="0"
        room_name="Single Room">
    <rates>

      <!-- Inactive rate -->
      <rate id="4545454"
            max_persons="1"
            policy="Non-Refundable"
            policy_id="88888888"
            rate_name="Non-Refundable Rate" />

      <!-- Active rate -->
      <rate id="6767676"
            max_persons="1"
            policy="General"
            policy_id="99999999"
            rate_name="Special Rate"
            readonly="1" />
    </rates>
  </room>
</rooms>

If <show_rates_status> 1 </show_rates_status> (only show Active rates):

<rooms>
  <room id="11111101"
        hotel_id="111111"
        hotel_name="Fake Hotel"
        max_children="0"
        room_name="Single Room">
    <rates>
      <rate id="6767676"
            max_persons="1"
            policy="General"
            policy_id="99999999"
            rate_name="Special Rate"
            readonly="1" />
    </rates>
  </room>
</rooms>

If <show_rates_status> 2 </show_rates_status> (show All rates with @active status):

<rooms>
  <room id="11111101"
        hotel_id="111111"
        hotel_name="Fake Hotel"
        max_children="0"
        room_name="Single Room">
    <rates>
      <rate id="4545454"
            active="0"
            max_persons="1"
            policy="Non-Refundable"
            policy_id="88888888"
            rate_name="Non-Refundable Rate" />
      <rate id="6767676"
            active="1"
            max_persons="1"
            policy="General"
            policy_id="99999999"
            rate_name="Special Rate"
            readonly="1" />
    </rates>
  </room>
</rooms>

Errors/Warnings

Common errors with this call include:

<?xml version='1.0' standalone='yes'?>
<roomrates>
  <fault code="401" string="Authorization Required" />
</roomrates>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXX==] -->

The usual solution is for the Connectivity Partner to double-check the login credentials being used, and that required nodes are not missing from the XML message body.

Another issue that can arise is an empty rooms node:

<rooms>
</rooms>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXX==] -->

This generally means that Booking.com has an incomplete or invalid setup for 1) Rooms, 2) Rates, 3)Policies and/or 4) Rate Rewrite setup (a configuration on the Booking.com extranet). In these cases, try doing a rooms call and rates. If information populates on these calls, there could be a policy setup error. In any case, please contact your Booking.com operational support contact.

Features

Include extra info in RoomRates call

This feature will add some useful info to the RoomRates API call response.
1- Include policy code for cancellation and prepayment
2- Include policy overrides codes. You will need to specify 2 additional elements in the request "policy_override_start_date" and "policy_override_end_date". Either both should be presented or none of them. These 2 elements will specify the date range you need to search for. We recommend the range to be maximum 30 days between start and end dates.
3- Include booking rules
4- Include rate relation(parent-child rate)(master-slave relation)
5- Include pricing types. in this new section you can get the pricing type for the room rate (Standard, RLO, OBP, LOS).
6- Include meal plan code.

Enable this feature to get full inventory information for roomrateavailability.

<rooms>
  <room id="11111102"
        hotel_id="111111"
        hotel_name="Fake Hotel"
        max_children="0"
        room_name="Double Room"
        readonly="1">
    <rates>
      <rate id="2323232"
            max_persons="2"
            policy="General"
            policy_id="99999999"
            rate_name="Standard Rate"
            is_child_rate="1">
            <meal_plan meal_plan_code="1"/>
            <policies>
                <booking_rules>
                    <booking_rule min_advanced_booking_offset="P1D"/>
                </booking_rules>
                <cancel_policy>
                    <cancel_penalty policy_code="1"/>
                </cancel_policy>
                <guarantee_payment_policy>
                    <guarantee_payment policy_code="1"/>
                </guarantee_payment_policy>
            </policies>
            <pricing type="Standard" price1="1"/>
            <rate_relation follows_closed="3" 
                           follows_restrictions="1" 
                           follows_room_rate_properties="0" 
                           follows_policygroup_id="1" 
                           follows_price="1" 
                           parent_rate_id="10318858" 
                           percentage="85"/>
      </rate>
      <rate id="4545454"
            max_persons="2"
            policy="Non-Refundable"
            policy_id="88888888"
            rate_name="Non-Refundable Rate" />
      <rate id="6767676"
            max_persons="2"
            policy="General"
            policy_id="99999999"
            rate_name="Special Rate"
            readonly="1">
            <meal_plan meal_plan_code="1"/>
            <policies>
                <booking_rules>
                    <booking_rule min_advanced_booking_offset="P1D"/>
                    <booking_rule release_time_of_day_start="41"/>
                </booking_rules>
                <cancel_policy>
                    <cancel_penalty policy_code="1"/>
                </cancel_policy>
                <guarantee_payment_policy>
                    <guarantee_payment 
                     policy_code="1"
                     effective_from="after_reservation_is_made"/>
                </guarantee_payment_policy>
            </policies>
            <pricing type="RLO">
              <occupancy persons="2" additional="20.5" round="0"/>
              <occupancy persons="1" percentage="80" round="0"/>
            </pricing>
        </rate>
    </rates>
  </room>
</rooms>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXX==] -->

Response — Feature Attributes(@) Overview

  • The @guarantee_payment_policy indicates if and when when the prepayment will be charge on the roomrate. Either after_cancellation_fee_begins or after_reservation_is_made
  • The @booking_rule defines restriction on the roomrate on when it can be booked.
  • The @cancel_policy defines the Booking.com policy that will be applicable in case of cancellation of a booking on that roomrate.
  • The @meal_plan_code defines the Booking.com mealplan code applicable on that policy.
  • The **@release_time_of_day_start specifies the time of day when a stay can be stopped for booking. The number represents time in 15-minute increments. E.g. 41 means 10:15am.