RateManager+ Documentation (2017 - 2018)

By -
Contributed body text content & English language copy-editing for partner-facing technical documentation for BookingSuite's RateManager+ tool.
Below is a full copy of this documentation as it existed in July 2018.
BookingSuite RateManager Specifications

Introduction

The following specification will explain how to connect your software with RateManager, a product of BookingSuite.
RateManager combines user-friendly design and accessible rate recommendations to help hotels of all shapes and sizes improve revenue performance and strengthen their overall business. We recommend watching this video to learn more about the services that Ratemanager provides.

Conventions

1-way, 2-way

We define connectivity as 1-way or 2-way.
1-way refers solely to data transfer from your PMS to RateManager. This means that we will only be able to receive data from your system.
2-way refers to data transfer from your PMS to RateManager, and RateManager rate updates back to your PMS.

Reservation data

Reservation data refers to all the data linked to a booking, any or all of which can impact the occupancy of a property. To make sure RateManager has everything it needs, please provide all information regarding sold rooms, as well as out-of-order/out-of-inventory rooms. Please do not send any dummy rooms.
The most basic functions of our RateManager product are dependent on computing the right occupancy and revenue, which is based on the data you provide us with. We need at least the following information per booking:
  • a unique reservation ID to identify the booking, and update it if needed
  • a check-in and check-out date
  • a booking date
  • a status indicator, at least for cancellations, that has an impact on the final occupancy
  • an average rate. We recommend providing the exact rate per night, to avoid discrepancies between your reports and the ones we provide
However, in addition to this core data, RateManager can also analyze additional segmentation data to provide more nuanced recommendations. By providing all information requested in this specification, we can provide the maximum benefits of RateManager to our mutual customers.

Property set-up process

Once the interface has been completed between RateManager and your PMS, we will be using a standardized process to set-up RateManager for new properties.
It is important to understand that we use a property’s historical data to train our algorithm for that specific property. To this end, for each property set-up, a complete history of 2 years will be requested from you. This historical data will only be requested once, at the beginning of set-up. Afterwards, we will only need to update new data as it comes in.

Property setup:

  1. Make the necessary configurations, depending of the methods and conventions used (hotel code mapping, FTP access, username and password set-up)
  2. PMS sends all reservations with check-out date <= Today (2 years of history is required)
  3. PMS sends all reservations with check-out date > Today (current and future data)
  4. PMS sends inventory for all room types, 365 days into the future (including Today)
  5. PMS activates live updates for new changes to reservations and inventory

Development Process

Roadmap

We usually develop with PMS partners by following this roadmap:
  1. Scoping call after reading this documentation to confirm the process, answer any questions, and set development expectations
  2. Development of inventory message (HotelInvCountNotifRQ)
  3. Development of reservation message (HotelResNotifRQ) and group block messages (HotelInvBlockNotifRQ, optional)
  4. Development of the rate update
  5. Testing the connection
  6. Testing with real data from pilot property
  7. Pilot testing with property
  8. Defining procedures for new property set-up

Testing process

Once development of both the 1-way and 2-way connections are complete, we will check basic scenarios to see if messages are being sent correctly, and if the resulting data is valid for our system.
We will test the following scenarios:
  • Create, modify, and cancel a single reservation
  • Create, modify, and cancel a group reservation
  • Create, modify, and cancel a group block (optional)
  • Push a single rate, and verify that the rate in the PMS is updated
  • Push multiple rates, and verify that all selected rates in the PMS are updated

Testing with Postman

The BookingSuite RateManager API collection can be easily imported into Postman, by clicking the button below:
Postman is a free application that allows you to execute test calls in an intuitive interface. When making test calls, you should use the sandbox environment. If you were not provided a sandbox, please request it at bookingsuite.connectivity@booking.com or via the help button.

Getting Started

Overview

API endpoint
https://ratemanager.booking.com/api/htng_message
Our specification is based on the HTNG 2013B specification, as created by the Hotel Technology Next Generation Association. All relevant code and details that we use will be explained in the following sections for your convenience. Refer to the HTNG 2013B specification at your own discretion and necessity.
The XML messages that will be sent and received are to be written in SOAP Message structure. We support both SOAP 1.1 and 1.2 versions. Specifically, these messages are:
From PMS to BookingSuite RateManager (1-Way Connection):
  • OTA_HotelInvCountNotifRQ message to post inventory data (number of rooms built, sold available…)
  • OTA_HotelResNotifRQ message to post reservation creation, modification, cancellation
  • OTA_HotelInvBlockNotifRQ message to post group block allocation creation, modification, cancellation
From BookingSuite RateManager to the PMS or Channel manager (2-Way Connection):
  • OTA_RatePlanNotifRQ message: BookingSuite RateManager posts rates triggered by user’s validation on our website.

Authentication

Authentication
<Header>
  <Security mustUnderstand="true">
    <UsertextToken>
      <Username>username_goes_here</Username>
      <Password>password_goes_here</Password>
    </UsertextToken>
  </Security>
</Header>
We authenticate inbound messages with the SOAP protocol’s <Security> field. We will provide you with a username and password to put into the header.
Without this block, you will get a 400 error with the error message: “SOAP Header not valid”.
You should receive credentials when beginning the development phase - if not, please contact bookingsuite.connectivity@booking.com.

Message type summary

HTNG type Goal Mandatory? Direction
OTA_HotelResNotifRQ Receiving property reservation data Yes PMS -> RateManager
OTA_HotelInvCountNotifRQ Receiving property inventory data Yes PMS -> RateManager
OTA_HotelInvBlockNotifRQ Receiving property group block data No PMS -> RateManager
OTA_RatePlanNotifRQ Receiving rate update validated by the customer Yes RateManager -> PMS
OTA_HotelProductRS Receiving property configuration information No PMS -> RateManager

Send Inventory

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
      soap:mustUnderstand="1">
      <wsse:UsertextToken>
        <wsse:Username>username</wsse:Username>
        <wsse:Password>password</wsse:Password>
      </wsse:UsertextToken>
    </wsse:Security>
    <wsa:MessageID>unique_message_ID</wsa:MessageID>
    <wsa:To>https://ratemanager.booking.com/api/htng_message</wsa:To>
  </soap:Header>
  <soap:Body>
    <OTA_HotelInvCountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05">
      <Inventories HotelCode="45121140">
        <Inventory>
          <StatusApplicationControl Start="2017-05-01" InvTypeCode="King" IsRoom="true"/>
          <InvCounts>
            <InvCount CountType="1" Count="20"/>
            <InvCount CountType="2" Count="15"/>
            <InvCount CountType="4" Count="3"/>
            <InvCount CountType="5" Count="2"/>
            <InvCount CountType="3" Count="0"/>
            <InvCount CountType="6" Count="0"/>
            <InvCount CountType="8" Count="0"/>
          </InvCounts>
        </Inventory>
        <Inventory>
          <StatusApplicationControl Start="2017-05-01" InvTypeCode="Deluxe" IsRoom="true"/>
          <InvCounts>
            <InvCount CountType="1" Count="13"/>
            <InvCount CountType="2" Count="10"/>
            <InvCount CountType="4" Count="1"/>
            <InvCount CountType="5" Count="2"/>
            <InvCount CountType="3" Count="0"/>
            <InvCount CountType="6" Count="0"/>
            <InvCount CountType="8" Count="0"/>
          </InvCounts>
        </Inventory>
        <Inventory>
          <StatusApplicationControl Start="2017-05-02" InvTypeCode="King" IsRoom="true"/>
          <InvCounts>
            <InvCount CountType="1" Count="20"/>
            <InvCount CountType="2" Count="10"/>
            <InvCount CountType="4" Count="9"/>
            <InvCount CountType="5" Count="1"/>
            <InvCount CountType="3" Count="0"/>
            <InvCount CountType="6" Count="0"/>
            <InvCount CountType="8" Count="0"/>
          </InvCounts>
        </Inventory>
        <Inventory>
          <StatusApplicationControl Start="2017-05-02" InvTypeCode="Deluxe" IsRoom="true"/>
          <InvCounts>
            <InvCount CountType="1" Count="13"/>
            <InvCount CountType="2" Count="5"/>
            <InvCount CountType="4" Count="6"/>
            <InvCount CountType="5" Count="2"/>
            <InvCount CountType="3" Count="0"/>
            <InvCount CountType="6" Count="0"/>
            <InvCount CountType="8" Count="0"/>
          </InvCounts>
        </Inventory>
      </Inventories>
    </OTA_HotelInvCountNotifRQ>
  </soap:Body>
</soap:Envelope>
The Hotel Inventory Count message provides the ability for a PMS to post inventory amounts.
We support the following inventory codes (CountType in the message body):
  • 1 Physical - number of rooms/units physically existing on the property
  • 2 Definitive availability - number of rooms/units available, minus number of allotments still available
  • 3 Tentative availability - number of allotments still available
  • 4 Definitive sold - number of rooms/units sold - status is confirmed
  • 5 Tentative sold - number of rooms/units sold - status is option
  • 6 Out of order - number of rooms/units temporarily unavailable (e.g. remodel, repair, etc.)
  • 8 Out of inventory - number of rooms/units which are indefinitely unavailable (e.g. construction)
You should send an update for all the dates and room types modified after each inventory modification.
It is also required to send a full inventory update every 24 hours to correct any missed messages.
If it is not possible to send only the dates and room types modified, instead send a full update every hour (all room types, full horizon 365 days).
Fields we consider
HotelCode Maps the message to a specific property. You will receive the hotel code for each new property from BookingSuite.
Inventory One <Inventory> block is given for one date and one room type of the inventory update.
Start The stay date to be processed. The date format has to be YYYY-MM-DD
InvTypeCode Room type code.
IsRoom Indicates whether the room type is a real hotel room or a dummy/pseudo room.
InvCount One <InvCount> block defines the inventory count for one given status, for the considered date and room type.

The CountType defines the room status based on the list above.
The Count is the value of the updated inventory.

Send Reservations

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsertextToken>
        <wsse:Username>username</wsse:Username>
        <wsse:Password>password</wsse:Password>
      </wsse:UsertextToken>
    </wsse:Security>
    <wsa:MessageID>unique_message_ID</wsa:MessageID>
    <wsa:To>https://ratemanager.booking.com/api/htng_message</wsa:To>
  </soap:Header>
  <soap:Body>
    <OTA_HotelResNotifRQ ResStatus="Commit" TimeStamp="2017-04-04T10:01:29+01:00">
      <HotelReservations>
        <HotelReservation CreateDateTime="2017-04-04T10:00:15+01:00" ResStatus="Reserved">
          <UniqueID ID="34880"/>
          <POS>
            <Source>
              <BookingChannel>
                <CompanyName Code="OTA">WEB</CompanyName>
              </BookingChannel>
            </Source>
          </POS>
          <RoomStays>
            <RoomStay MarketCode="Leisure" SourceOfBusiness="BOOKING.COM">
              <RoomRates>
                <RoomRate InvBlockCode="" NumberOfUnits="1" RatePlanCode="BAR" RoomTypeCode="King" IsRoom="true">
                  <Rates>
                    <Rate EffectiveDate="2017-05-01" ExpireDate="2017-05-02" RateTimeUnit="Night" UnitMultiplier="1">
                      <Base AmountAfterTax="39.00" CurrencyCode="GBP"/>
                    </Rate>
                    <Rate EffectiveDate="2017-05-02" ExpireDate="2017-05-03" RateTimeUnit="Night" UnitMultiplier="1">
                      <Base AmountAfterTax="49.00" CurrencyCode="GBP"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="2"/>
                <GuestCount AgeQualifyingCode="8" Count="0"/>
              </GuestCounts>
              <BasicPropertyInfo HotelCode="45121140"/>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <Address>
                        <CountryName Code="UK"/>
                      </Address>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
        </HotelReservation>
        <HotelReservation CreateDateTime="2017-04-15T10:00:13+01:00" ResStatus="Reserved">
          <UniqueID ID="42689"/>
          <POS>
            <Source>
              <BookingChannel>
                <CompanyName Code="Comp">Company</CompanyName>
              </BookingChannel>
            </Source>
          </POS>
          <RoomStays>
            <RoomStay MarketCode="Corp" SourceOfBusiness="Special Company">
              <RoomRates>
                <RoomRate InvBlockCode="" NumberOfUnits="1" RatePlanCode="CORP" RoomTypeCode="Deluxe" IsRoom="true">
                  <Rates>
                    <Rate EffectiveDate="2017-05-01" ExpireDate="2017-05-02" RateTimeUnit="Night" UnitMultiplier="1">
                      <Base AmountAfterTax="55.00" CurrencyCode="EUR"/>
                    </Rate>
                    <Rate EffectiveDate="2017-05-02" ExpireDate="2017-05-03" RateTimeUnit="Night" UnitMultiplier="1">
                      <Base AmountAfterTax="59.00" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <GuestCounts IsPerRoom="1">
                <GuestCount AgeQualifyingCode="10" Count="2"/>
                <GuestCount AgeQualifyingCode="8" Count="0"/>
              </GuestCounts>
              <BasicPropertyInfo HotelCode="45121140"/>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <Address>
                        <CountryName Code="DE"/>
                      </Address>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResNotifRQ>
  </soap:Body>
</soap:Envelope>
This endpoint posts a new reservation creation, modification or cancellation to BookingSuite RateManager. The immediate response is a standard HTTP code (Ack / Nack).
Each OTA_HotelResNotifRQ message can contain up to 1000 reservations for a single hotel. These reservations are in a <HotelReservation> block, and must be gathered under the same transactional status.
Fields we consider
OTA_ResNotifRQ
ResStatus		 Transactional status of the reservation. It can be:
- ‘Commit’ (creates a new reservation)
- ‘Modify’ (updates an existing reservation)
- ‘Cancel’ (cancels a reservation)
<HotelReservation> Reservation block. We accept up to 1000 blocks.
CreateDateTime This is what we consider as the booking date. Please ensure the timezone matches that of the property. Format 2016-10-09T08:51:45 UTC
HotelReservation
ResStatus		 Reservation status. It can be:
- Reserved (confirmed reservation)
- Waitlisted(reservation on waitlist)
- In-House (in-house booking)
- Checked-Out (already checked-out reservation)
- Cancelled (already cancelled reservation)
UniqueID Unique reservation ID of the reservation that will permit us to link your message to the reservation in our database.
HotelCode Maps the message to a specific property. You will receive the hotel code for each new property from BookingSuite.
CompanyName We take this block as the source of the booking.
‘Code’ specifies the source (web, OTA, email, etc.), while the field is the general channel (Walk-in, WEB, TEL).
RoomStay One <Roomstay> block is one room booked for the given reservation.
MarketCode MarketCode is the intent of the stay, and what we take as segmentation data (leisure, corporate, etc).
SourceOfBusiness SourceOfBusiness is what we take as the agency.
RoomRate One <RoomRate> block represents one rate for one rate plan and one room type.
RoomTypeCode Room type. It must match the InvTypeCode in inventory messages.
IsRoom Indicates whether the reservation is for a real hotel room or a dummy room.
RatePlanCode Rate plan used for this reservation
NumberOfUnits Number of rooms under the same roomtype and rate plan.
InvBlockCode If the room booked is part of a block, the block ID is transferred in this field.
Rate One <Rate> block is for one amount for the given rate plan and room type for a given period.
EffectiveDate
ExpireDate		 Dates to define the time range of the <Rate>. We consider that one rate is applied for one night.
AmountAfterTax
CurrencyCode		 Amount for the given rate plan, room type, time period, and its currency (in ISO 4217).
AgeQualifyingCode This block represents the number of people in the <RoomStay>. The AgeQualifyingCode=10 is the number of adults (in Count value), and AgeQualifyingCode=8 is the number of children.
CountryName The only information we take from guests is their country of origin for segmentation analysis.

Send Group Blocks

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
xmlns:wsa="http://www.w3.org/2005/08/addressing" 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <soap:Header>
    <wsse:Security soap:mustUnderstand="1">
      <wsse:UsernameToken>
        <wsse:Username>username</wsse:Username>
        <wsse:Password>password</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
    <wsa:MessageID>8ee65699-8b8b-8427-2822-687da8b55a89</wsa:MessageID>
    <wsa:To>https://ratemanager.booking.com/api/htng_message</wsa:To>
  </soap:Header>
  <soap:Body>
    <OTA_HotelInvBlockNotifRQ TimeStamp="2017-05-04T14:03:10+01:00">
      <InvBlocks>
        <InvBlock InvBlockCode="FANCY_CONGRESS" TransactionAction="Book">
          <HotelRef HotelCode="45121140"/>
          <InvBlockDates AbsoluteCutoff="2017-06-01" End="2017-06-04" Start="2017-06-01"/>
          <RoomTypes>
            <RoomType RoomTypeCode="Double">
              <RoomTypeAllocations RoomTypePickUpStatus="2">
                <RoomTypeAllocation Start="2017-06-01" End="2017-06-01" NumberOfUnits="1"/>
              </RoomTypeAllocations>
              <RatePlans>
                <RatePlan RatePlanCode="GROUP1">
                  <BaseByGuestAmts>
                    <BaseByGuestAmt AmountAfterTax="105.00" CurrencyCode="EUR" NumberOfGuests="1"/>
                  </BaseByGuestAmts>
                </RatePlan>
              </RatePlans>
            </RoomType>
            <RoomType RoomTypeCode="King">
              <RoomTypeAllocations RoomTypePickUpStatus="4">
                <RoomTypeAllocation Start="2017-06-01" End="2017-06-04" NumberOfUnits="5"/>
              </RoomTypeAllocations>
              <RatePlans>
                <RatePlan RatePlanCode="GROUP2">
                  <BaseByGuestAmts>
                    <BaseByGuestAmt AmountAfterTax="90" CurrencyCode="EUR" NumberOfGuests="1"/>
                  </BaseByGuestAmts>
                </RatePlan>
              </RatePlans>
            </RoomType>
            <RoomType RoomTypeCode="King">
              <RoomTypeAllocations RoomTypePickUpStatus="2">
                <RoomTypeAllocation Start="2017-06-01" End="2017-06-04" NumberOfUnits="3"/>
              </RoomTypeAllocations>
              <RoomTypeAllocations RoomTypePickUpStatus="4">
                <RoomTypeAllocation Start="2017-06-01" End="2017-06-04" NumberOfUnits="1"/>
              </RoomTypeAllocations>
              <RatePlans>
                <RatePlan Start="2017-06-01" End="2017-06-02" RatePlanCode="GROUP2">
                  <BaseByGuestAmts>
                    <BaseByGuestAmt AmountAfterTax="95" CurrencyCode="EUR" NumberOfGuests="1"/>
                  </BaseByGuestAmts>
                </RatePlan>
              </RatePlans>
            </RoomType>
            <RoomType RoomTypeCode="Twin">
              <RoomTypeAllocations>
                <RoomTypeAllocation Start="2017-06-01" End="2017-06-04" NumberOfUnits="1"/>
              </RoomTypeAllocations>
              <RatePlans>
                <RatePlan Start="2017-06-01" End="2017-06-02" RatePlanCode="GROUP2">
                  <BaseByGuestAmts>
                    <BaseByGuestAmt AmountAfterTax="220" CurrencyCode="HRK" NumberOfGuests="1"/>
                  </BaseByGuestAmts>
                </RatePlan>
                <RatePlan Start="2017-06-02" End="2017-06-04" RatePlanCode="GROUP3">
                  <BaseByGuestAmts>
                    <BaseByGuestAmt AmountAfterTax="110" CurrencyCode="HRK" NumberOfGuests="1"/>
                  </BaseByGuestAmts>
                </RatePlan>
              </RatePlans>
            </RoomType>
          </RoomTypes>
        </InvBlock>
      </InvBlocks>
    </OTA_HotelInvBlockNotifRQ>
  </soap:Body>
</soap:Envelope>
This message permits RateManager to be alerted about a group block. We consider a group block to be a large booking (generally more than 10 rooms) that needs to be confirmed by participants and is under a specific expiration policy.
We use the HTNG 2013 specification to define the number of rooms blocked, and already sold. Each message should contain one block (one unique block id) for a single hotel. The message processing happens like this:
  1. We cross all room types, for each room type we cross all rate plans applied and save them in memory
  2. We cross all counts of each block and attach them to one room type and one rate plan
  3. Finally, we consider each day of the group block to create one booking with the right room type, rate plan and number of units blocked or sold
Fields we consider
InvBlock It’s the block allocation block. We accept one InvBlock block for now.
TransactionAction The transactional status of the block. It can be:
- ‘Book’ (creates a new reservation)
- ‘Modify’ (updates an existing reservation)
- ‘Cancel’ (cancels a reservation)
InvBlockCode The unique block ID that allow us to link all future messages to the right block in our database.
HotelCode Maps the message to a specific property. You will receive the hotel code for each new property from BookingSuite.
InvBlockDates Global dates of the block considered. Start is the start date, End the end date, and AbsoluteCutoff is the release date of the block.
We consider the block released where AbsoluteCutoff <= Today (including today)
RoomType One RoomType block is the piece of the block with a given room type and rate plan.
If there is only one rate plan and 2 different room types for the block, there will be at least 2 RoomType blocks.
CompanyName We take this block as the source of the booking.
‘Code’ specifies the source (web, OTA, email, etc.), while the field is the general channel (Walk-in, WEB, TEL).
RatePlan One RatePlan block gives the description of the rate plan for the given room type and time range.
RatePlanCode The RatePlanCode is the rate plan code that will be shown and considered in our database, the CurrencyCode the currency for the given rate plan (in ISO 4217).
BaseByGuestAmt One BaseByGuestAmt allow to give the amount depending of the number of people that will finally be confirmed in the booking. We save in our database only the amount for NumberOfGuests = 1
AmountAfterTax The amount after tax for the given rate plan. We don’t save the amount before tax.
RoomTypeAllocations RoomTypeAllocations defines the number of units per status. The statuses we consider are:
- 1 Definite availability
- 2 Tentative availability
- 3 Definite sold
- 4 Tentative sold
RoomTypeAllocation One RoomTypeAllocation line gives the number of units for the given RoomTypePickupStatus and a considered time range (starting with Start, finishing with End).
Generally, Start=End.

Receive Rate Updates

This message allows us to notify your system about rate updates that a property would like to perform, and lets you handle channel management. These rate updates can be triggered manually by the property, or automatically according to RateManager settings decided by the property (difference with the current price, dates, etc…).
The message contains the list of the new prices for different check-in dates and their corresponding conditions (room type, the number of guests, and the rate plan). Since our Revenue Management System and your system use different codes (hotel codes, room codes, etc.), we should agree beforehand on which system codes we should use in the message. By default, we assume we will use all your system codes. Please let us know if you want to do otherwise.

Push Mode (POST from RateManager to your system)

Request body from RateManager to provider - POST url provided by you
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:htng="http://htng.org/PWSWG/2007/02/AsyncHeaders">
    <wsa:MessageID>9ff77969-348d-4ed5-bc64-e7a5df4f0f9b</wsa:MessageID>
    <htng:CorrelationID>9ff77969-348d-4ed5-bc64-e7a5df4f0f9b</htng:CorrelationID>
    <wsa:To>https://partners.url.com</wsa:To>
    <wsa:Action>http://htng.org/PWSWG/2010/12/RatePlan_SubmitRequest</wsa:Action>
    <wsa:ReplyTo>
      <wsa:Address>https://partners.url.com</wsa:Address>
    </wsa:ReplyTo>
    <htng:ReplyTo>
      <wsa:Address>https://ratemanager.booking.com/api/rate_push_callback</wsa:Address>
    </htng:ReplyTo>
    <wsse:Security soap:mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>username</wsse:Username>
        <wsse:Password>password</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <OTA_HotelRatePlanNotifRQ TimeStamp="2016-12-05T14:57:29+00:00" Version="6.000" MessageContentCode="8">
      <RatePlans HotelCode="13864">
        <RatePlan RatePlanCode="BAR" RatePlanNotifType="Delta">
          <Rates>
            <Rate Start="2017-03-05" End="2017-03-05" CurrencyCode="EUR" InvTypeCode="DOUBLE">
              <BaseByGuestAmts>
                <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="153" />
                <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="173" />
              </BaseByGuestAmts>
            </Rate>
            <Rate Start="2017-03-05" End="2017-03-05" CurrencyCode="EUR" InvTypeCode="KING">
              <BaseByGuestAmts>
                <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="163.0" />
              </BaseByGuestAmts>
            </Rate>
          </Rates>
        </RatePlan>
      </RatePlans>
    </OTA_HotelRatePlanNotifRQ>
  </soap:Body>
</soap:Envelope>
Callback from Provider to RateManager - POST https://ratemanager.booking.com/api/rate_plan_notif_callback
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <wsa:Action>http://htng.org/PWSWG/2010/12/RatePlan_SubmitResult</wsa:Action>
    <wsa:MessageID>1bad9bd8-8fd2-e495-f023-82234ce4bec7</wsa:MessageID>
    <wsa:RelatesTo>9ff77969-348d-4ed5-bc64-e7a5df4f0f9b</wsa:RelatesTo>
  </soap:Header>
  <soap:Body>
    <OTA_HotelRatePlanNotifRS TimeStamp="2016-12-05T14:57:31+00:00">
      <Success />
    </OTA_HotelRatePlanNotifRS>
  </soap:Body>
</soap:Envelope>
You must provide a web service to which we can send HTTP POST requests with the OTA_HotelRatePlanNotifRQ message inside a SOAP envelope as the body. You have to apply the updates asynchronously: this means you have to respond to our POST before trying to send the rate updates to any other system. The response should be quick, regardless of the number of rate updates, and any costly computation that takes more than few seconds should be performed asynchronously.
You must also inform us about the success or the failure of the rate push by sending a POST request to the callback url. If the update failed, you must provide us with a helpful error message to understand the issue. It will help us fix a whole range of problems without involving your support team, and make communication easy and efficient. You should provide different error messages for the following errors:
  • If the username/password is wrong
  • If the connection is not activated/configured
  • If the hotel code is not correct or not associated with the username/password.
  • If the rate plan is wrong
  • If one of the room codes is wrong (please specify which code(s))
  • If anything else prevented the success of the rate update
Fields we consider
MessageID The MessageID should be used inside the asynchronous callback message.
Address The URL to send the asynchronous call back message.
UsernameToken This field will contain your web service credentials. It can be one username/password for all properties, or a different username/password for each property.
HotelCode The Hotel Code variable maps the message to a specific property. You will receive the hotel code for each new property from BookingSuite.
RatePlanCode The rate policy code we refer to. If your system doesn’t support different rate policies, we can send a default value like BAR.
Start
End		 The date range attributes. Both are inclusive.
CurrencyCode The currency considered for this rate block.
InvTypeCode InvTypeCode can be anything that enable us to uniquely identify a room type for a given hotel. It could be a room type or a room code (your choice).
BaseByGuestAmt
NumberOfGuests
AmountAfterTax		 NumberOfGuests is the number of guests considered for the given amount, rate policy and room type.
AmountAfterTax is a positive numeric value that is the rate to apply for the given rate policy, room type and number of people.

Pull Mode (GET from your system to RateManager)

GET https://ratemanager.booking.com/api/retrieve_responses?hotel_code=hotelcode&username=user&password=pass
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:htng="http://htng.org/PWSWG/2007/02/AsyncHeaders">
    <wsa:MessageID>9ff77969-348d-4ed5-bc64-e7a5df4f0f9b</wsa:MessageID>
    <htng:CorrelationID>9ff77969-348d-4ed5-bc64-e7a5df4f0f9b</htng:CorrelationID>
    <wsa:To>https://partners.url.com</wsa:To>
    <wsa:Action>http://htng.org/PWSWG/2010/12/RatePlan_SubmitRequest</wsa:Action>
    <wsa:ReplyTo>
      <wsa:Address>https://partners.url.com</wsa:Address>
    </wsa:ReplyTo>
    <htng:ReplyTo>
      <wsa:Address>https://ratemanager.booking.com/api/rate_push_callback</wsa:Address>
    </htng:ReplyTo>
    <wsse:Security soap:mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>username</wsse:Username>
        <wsse:Password>password</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <OTA_HotelRatePlanNotifRQ TimeStamp="2016-12-05T14:57:29+00:00" Version="6.000" MessageContentCode="8">
      <RatePlans HotelCode="13864">
        <RatePlan RatePlanCode="BAR" RatePlanNotifType="Delta">
          <Rates>
            <Rate Start="2017-03-05" End="2017-03-05" CurrencyCode="EUR" InvTypeCode="DOUBLE">
              <BaseByGuestAmts>
                <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="153" />
                <BaseByGuestAmt NumberOfGuests="2" AgeQualifyingCode="10" AmountAfterTax="173" />
              </BaseByGuestAmts>
            </Rate>
            <Rate Start="2017-03-05" End="2017-03-05" CurrencyCode="EUR" InvTypeCode="KING">
              <BaseByGuestAmts>
                <BaseByGuestAmt NumberOfGuests="1" AgeQualifyingCode="10" AmountAfterTax="163.0" />
              </BaseByGuestAmts>
            </Rate>
          </Rates>
        </RatePlan>
      </RatePlans>
    </OTA_HotelRatePlanNotifRQ>
  </soap:Body>
</soap:Envelope>
Callback from Provider to RateManager - POST https://ratemanager.booking.com/api/rate_plan_notif_callback
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <wsa:Action>http://htng.org/PWSWG/2010/12/RatePlan_SubmitResult</wsa:Action>
    <wsa:MessageID>1bad9bd8-8fd2-e495-f023-82234ce4bec7</wsa:MessageID>
    <wsa:RelatesTo>9ff77969-348d-4ed5-bc64-e7a5df4f0f9b</wsa:RelatesTo>
  </soap:Header>
  <soap:Body>
    <OTA_HotelRatePlanNotifRS TimeStamp="2016-12-05T14:57:31+00:00">
      <Success />
    </OTA_HotelRatePlanNotifRS>
  </soap:Body>
</soap:Envelope>
You can also choose to collect the rate updates from our system via a GET. In this mode, you should hit our endpoint periodically, ideally every 5 minutes or so, to receive the rate updates that haven’t been sent yet.
GET https://ratemanager.booking.com/api/retrieve_responses?hotel_code=hotelcode&username=user&password=pass
This endpoint works as a queueing system. Meaning that when you send a GET request, If we have rate updates to send, you will get only the one on top of the queue, and we’ll delete it from our system. So that when you GET again, the next rate update will be send.
If we don’t have any rate updates to send, we’ll respond with a 204 status code (no content).
When receiving a rate, you should keep sending another GET request in a loop, until you receive a 204. That’s very important, otherwise you might get into a condition where you never manage to fetch all the rates updates we have.

Self Build

The entire process of signup and activation of the RateManager product can be automated. This will allow the hotel partner to sign up for RateManager product from within their Booking.com extranet, and activate the connection to the PMS/channel manager provider with a click of a button.

Full automation workflow

Signup

Redirect from RateManager signup to provider authentication screen:
304 to https://[provider_url.com]?hotel_code=12345&token=a2ed4f5
You need to provide us with a endpoint URL for new signups. BookingSuite will send a 304 with a unique token and the Booking.com hotel ID.
You need to be able to accept and validate the Booking.com ID and map it to your own hotel ID.
The hotel partner will be redirected to your domain with the Booking.com hotel ID and unique token. This should be an authentication screen where the hotel partner can then log in with their credentials, choose a property (if applicable) and accept terms (if any).
Redirect back to RateManager onboaridng process once successfully authenticated:
304 to https://ratemanager.booking.com/api/signup/complete_pms_redirection/a2ed4f5
Upon successfuly authentication, you should send us back a 304 with the same unique token.
The hotel partner will be redirected back to our onboarding platform to continue setup of their RateManager.
Once the hotel partner was successfully authenticated, you should trigger sending the hotel’s initial data (history, current, future reservations and inventory) and activate the interface.

Hotel Config

GET https://[provider_url.com]?hotel_code=123&username=me&password=hi
<?xml version="1.0"?>
<OTA_HotelProductRS>
<HotelProducts>
   <HotelProduct>
       <RoomTypes>
           <RoomType RoomTypeCode="3984" RoomTypeName="Double - Disabled Access" MaxOccupancy="2" NbrOfBedrooms="1" />
           <RoomType RoomTypeCode="3985" RoomTypeName="Double" MaxOccupancy="2" NbrOfBedrooms="5"/>
           <RoomType RoomTypeCode="3987" RoomTypeName="Executive Double" MaxOccupancy="2" NbrOfBedrooms="2"/>
           <RoomType RoomTypeCode="3988" RoomTypeName="Superior Double" MaxOccupancy="2" NbrOfBedrooms="3"/>
       </RoomTypes>
       <RatePlans>
           <RatePlan RatePlanCode="30327" RatePlanName="Bed and Breakfast"/>
           <RatePlan RatePlanCode="30332" RatePlanName="Corporate Bed and Breakfast"/>
       </RatePlans>
   </HotelProduct>
</HotelProducts>
</OTA_HotelProductRS>
In order to successfully set up the rate update we need to be able to map your rooms and rate plans to the calendar views in RateManager. You need to provide us with an endpoint we can call to get the hotel configuration.
Authentication should be handled within the URL and the credentials need to be the same as the ones used in other messages.
The response should include the following:
Room types
RoomTypeCode Room type code used in the inventory and reservation messages.
RoomTypeName Full name of the room. This will be displayed in reporting.
MaxOccupancy Maximum occupancy of that room type.
NbrOfBedrooms Total number of rooms of this type in the property.
Rate plans
RatePlanCode Rate plan code used in the reservation messages.
RatePlanName Full name of the rate plan. This will be displayed in reporting.

Reset - Re-sync

GET https://[provider_url.com]?hotel_code=123&username=me&password=hi
If an issue is found that causes data discrepancies, the original data upload needs to be a repeatable automated process. You need to provide us with an endpoint to call for the re-synchronization. Authentication should be handled within the URL and the credentials need to be the same as the ones used in other messages.
You should then trigger the initial data upload again (historical, in-house and future reservations, full inventory and group blocks). This must be posted to the usual endpoint (https://ratemanager.booking.com/api/htng_message)
The ongoing real-time updates to reservations and inventory should not be disrupted during this process.

Iframe

Iframe allows the RateIntelligence and RateManager tools to be accessed directly inside your PMS interface. This section will cover how to implement single sign-on for the RateManager iframe with code samples.

Single sign-on

RateManager will provide you with a “partner id”, private encryption, and HMAC keys. In order for the iframe to display, an encrypted token must be generated and passed to the URL so that RateManager can properly authenticate the user. This token is built from a JSON object containing the property’s Booking.com Hotel ID and the current timestamp in iso8601 format. If the Hotel ID doesn’t match to a known property, or the timestamp is older than 10 minutes, the token will be rejected.
The encryption token is constructed as follows:
  1. Generate a 16 byte random initialization vector (this has the same value in all code samples)
  2. Encrypt the JSON payload with AES 128 bit encryption, with the secret encryption key and initialization vector
  3. Prepend the randomly generated initialization vector to the encryption created, to get the ciphertext
  4. Compute the HMAC-SHA1 digest of that ciphertext using your secret HMAC key,
  5. Append that digest at the end of the ciphertext
  6. Finally, encode that result in base 64 to create the token
Once this token is created, let’s say abc123, if your partner_id is 456, the url to display the iframe will be
https://ratemanager.booking.com/partner/iframe?partner_id=456&token=abc123

Testing

You can test the iframe implementation using your secret keys and adding a /demo in the url:
https://ratemanager.booking.com/partner/iframe/demo?partner_id=456&token=abc123
This will redirect you to an anonymised demo account. Note that you will still need a valid Hotel ID, partner_id, and the current timestamp, in addition to URL encoding the token before passing it.
Create Modify Cancel