Outdated version

This documentation is outdated and is soon going to be deprecated. For the latest in Reservations API documentation, see the retrieving modified or cancelled reservations and acknowledging modified or cancelled reservations sections.

The following section is outdated and Booking.com does not actively verify its accuracy. Use at your own discretion.

HotelResModifyNotifRQ/RS (OTA 2003B)

This call is used for retrieving and responding to new modification/cancellations on Booking.com.

Steps for successful modification/cancellations retrieval

  1. Get request to OTA_HotelResModifyNotif URL. (By Provider).

  2. Booking.com will respond with a HotelResModifyNotifRQ, including a full list of open modification/cancellations (By Booking.com)

  3. Post request to OTA_HotelResModifyNotif URL with OTA_HotelResModifyNotifRS message indicating a success(check OTA_HotelResModifyNotifRS message formate below). (By Provider).

  4. Once Booking.com receives the confirmation that the modifications and/or cancellations were processed successfully, we will remove those modifications and/or cancellations from the queue.And respond back with OTA_HotelResModifyNotifRS success. (By Booking.com)

Note

If provider didn't respond with OTA_HotelResModifyNotifRS message (step 3), message will be sent as a fallback after a certain deadline.

Step 1: Send a GET request to this URL

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

Step 2: You will receive this response

HotelResModifyNotifRQ

Note

This example does not contain optional elements that Booking.com supports. Optional elements are defined in separate section below.

Virtual credit card (VCC) details are included in all retrievals

In case you retrieve a reservation multiple times, VCC details are included in all retrievals. However, ordinary credit card (CC) details are only included once (B.XML) or until the details are acknowledged (OTA).

<?xml version="1.0" encoding="UTF-8"?>
<HotelResModifyNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 HotelResModifyNotifRQ.xsd" TimeStamp="2012-11-13T10:06:51-00:00" Target="Production" Version="2.001">
   <HotelResModifies>
      <HotelResModify>
         <RoomStays>
            <RoomStay IndexNumber="369">
               <RoomTypes>
                  <RoomType RoomTypeCode="36745601">
                     <RoomDescription Name="Standard Double Room - Special conditions - Breakfast included,Lunch included,Dinner included">
                        <Text />
                        <MealPlan>All meals and select beverages are included in the room rate.</MealPlan>
                        <MaxChildren>0</MaxChildren>
                     </RoomDescription>
                     <Amenities>
                        <Amenity />
                     </Amenities>
                  </RoomType>
               </RoomTypes>
               <RatePlans>
                  <RatePlan>
                     <Commission>
                        <CommissionPayableAmount Amount="4500" DecimalPlaces="2" CurrencyCode="EUR" />
                     </Commission>
                  </RatePlan>
               </RatePlans>
               <RoomRates>
                  <RoomRate EffectiveDate="2012-12-13" RatePlanCode="1278608">
                     <Rates>
                        <Rate>
                           <Total AmountAfterTax="37000" DecimalPlaces="2" CurrencyCode="EUR" />
                        </Rate>
                     </Rates>
                  </RoomRate>
               </RoomRates>
               <GuestCounts>
                  <GuestCount Count="2" />
               </GuestCounts>
               <Total AmountAfterTax="37500" DecimalPlaces="2" CurrencyCode="EUR" />
               <BasicPropertyInfo HotelCode="367456" />
               <ResGuestRPHs>
                  <ResGuestRPH RPH="1" />
               </ResGuestRPHs>
               <Comments>
                  <Comment>
                     <Text>I need a wake up service</Text>
                  </Comment>
               </Comments>
               <SpecialRequests>
                  <SpecialRequest Name="smoking preference">
                     <Text>Non-Smoking</Text>
                  </SpecialRequest>
               </SpecialRequests>
               <ServiceRPHs>
                  <ServiceRPH RPH="1" />
               </ServiceRPHs>
            </RoomStay>
         </RoomStays>
         <Services>
            <Service ServiceRPH="1" ServiceInventoryCode="22" ServicePricingType="3">
               <ServiceDetails>
                  <TimeSpan Duration="1" />
                  <Fees>
                     <Fee Amount="5" />
                  </Fees>
               </ServiceDetails>
            </Service>
         </Services>
         <ResGuests>
            <ResGuest ResGuestRPH="1">
               <Profiles>
                  <ProfileInfo>
                     <Profile>
                        <Customer>
                           <PersonName>
                              <GivenName>FIRSTNAMEBOOKER</GivenName>
                              <Surname>LASTNAMEBOOKER</Surname>
                           </PersonName>
                        </Customer>
                     </Profile>
                  </ProfileInfo>
               </Profiles>
            </ResGuest>
         </ResGuests>
         <ResGlobalInfo>
            <Comments>
               <Comment>
                  <Text>SPECIAL REQUESTS</Text>
               </Comment>
            </Comments>
            <Guarantee>
               <GuaranteesAccepted>
                  <GuaranteeAccepted>
                     <PaymentCard CardCode="MC" CardNumber="5346330641608164" SeriesCode="" ExpireDate="0122">
                        <CardHolderName>CARD HOLDER NAME</CardHolderName>
                     </PaymentCard>
                  </GuaranteeAccepted>
               </GuaranteesAccepted>
            </Guarantee>
            <Total AmountAfterTax="37500" DecimalPlaces="2" CurrencyCode="EUR" />
            <HotelReservationIDs>
               <HotelReservationID ResID_Value="312637549" ResID_Date="2012-11-13T11:06:39" />
            </HotelReservationIDs>
            <Profiles>
               <ProfileInfo>
                  <Profile>
                     <Customer>
                        <PersonName>
                           <GivenName>FIRSTNAMEBOOKER</GivenName>
                           <Surname>LASTNAMEBOOKER</Surname>
                        </PersonName>
                        <Telephone PhoneNumber="+31 20 715 00 00" />
                        <Email />
                        <Address>
                           <AddressLine>ADDRESS</AddressLine>
                           <CityName>CITY</CityName>
                           <PostalCode>ZIP CODE</PostalCode>
                           <CountryName Code="NL" />
                           <CompanyName />
                        </Address>
                     </Customer>
                  </Profile>
               </ProfileInfo>
            </Profiles>
         </ResGlobalInfo>
      </HotelResModify>
   </HotelResModifies>
</HotelResModifyNotifRQ>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUMeu8mgftUJQvv83JiDhiMRratijIz/X6xcDosO3nt0XGuvxg8fgIxN0e0aGB0aiA==] -->

The above request will do the following: respond with new modification/cancellation messages. In order to complete the process of retrieving this modification/cancellation; the Connectivity Partner must POST a success message to

Step 3: Send acknowledge message

https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif

OTA_HotelResModifyNotif Response

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResModifyNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelResModifyNotifRS.xsd" TimeStamp="2012-10-16T15:39:55" Target="Production" Version="2.001">
   <Success />
   <HotelResModifies>
      <HotelResModify>
         <ResGlobalInfo>
            <HotelReservationIDs>
               <HotelReservationID ResID_Value="812864414" ResID_Source="BOOKING.COM" ResID_Type="14" />
               <HotelReservationID ResID_Value="OWNCODE64143566" ResID_Source="RT" ResID_Type="14" />
            </HotelReservationIDs>
         </ResGlobalInfo>
      </HotelResModify>
   </HotelResModifies>
</OTA_HotelResModifyNotifRS>

<HotelReservationID ResID_Value="812864414" ResID_Source="BOOKING.COM" ResID_Type="14" /> This line is mandatory and means that the reservation ID in Booking.com system = 812864414.

<HotelReservationID ResID_Value="OWNCODE64143566" ResID_Source="RT" ResID_Type="14" /> Include this line only if you enabled connection setting "Include External Reservation IDs in OTA messages"(Contact your Account manager)

It means that the ID of the reservation in your system = OWNCODE64143566. This ID will be sent to you again for any modification messages within HotelReservationIDs tag.

You need to enable connection setting "Include ResID_Source information in <HotelReservationID>" to have attribute ResID_Source. (Contact your Account manager)

In case of failure from your side, then send this, stating the errors happened:

<OTA_HotelResModifyNotifRS>
   <Errors>
      <Error Code="193" RecordID="1568716590" ShortText="Cancellation process failed"/>
   </Errors>
</OTA_HotelResModifyNotifRS>

Error@RecordID is the reservation ID

Step 4: You will receive this reponse.

Response

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResModifyNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelResModifyNotifRS.xsd" TimeStamp="2017-08-18T21:59:59+00:00" Target="Production" Version="2.001">
<Success />

</OTA_HotelResModifyNotifRS><!-- RUID: [UmFuZG9tSVYkc2RlIyh9YeeCUCBxnFs0Qa4qxnI5OukFZU8blOwMpru8prRknWlazRsCTDtyjYp/erygfshdjiuwfd] -->

The above request will do the following: Confirm modification/cancellation 812864414 and take the xml modification/cancellation message out of the queue. Please confirm every modification/cancellation message in separate requests.

Note, to confirm multiple modification/cancellation messages in one request, the <HotelResModify> tag can be used multiple times.

Optional parameters in the request URL

Element name: hotel_ids

Description: The hotel ID supplied by Booking.com to identify the hotel you are trying to retrieve modification/cancellations from.

Type: integer

Constraints: * When "id" is specified, the "hotel_ids" parameter has no effect. * You can add up to 500 hotel_ids per request. If you add more, you receive the following error:
invalid hotel_id value - you are not allowed to request more than 500 hotel ids per request

Format: multiple hotel ID's are separated by commas. All hotel IDs are unique.

Example:

https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?hotel_ids=10002,10003

Element name: id

Description: Short description Connectivity Partners are able to issue a modification/cancellation ID to retrieve a single modification/cancellation

Type: integer

Constraints: only IDs can be specified that are queued (or have been queued) for XML retrieval before. ID can only be specified if hotel_ids is omitted

Example:

https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?id=569603872

Element name: last_change

Description: Retrieves all modification/cancellations that have been made or modified since the specified date in the last_change element

Type: datetime

Constraints: you should only request modification/cancellations up until 2 weeks in the past.

Format: YYYY-MM-DD HH:MM:SS

The last change function will not contain any modification/cancellation messages that have never been queued for XML before. Connectivity Partners should only request modification/cancellations up until 2 weeks in the past. The last_change element will also result in modification/cancellations that have been picked up via XML before. last_change will return reservations starting from the oldest reservation. The exact number varies depending on our system, but please expect several hundred. This can be reduced by specifying limit.

Booking.com does not recommend an excessive use of the last_changed parameter as it may lead to unexpected behaviour. Use this parameter only when you have to recover lost data after an unexpected outage.

When retrieving reservations using the last_changed query parameter, the API response includes confirmations, modifications and cancellations that may have already been processed. Processing that response can impact your system's availability to:

  • Process new reservations.
  • Send acknowledgements in time.

Without the last_changed query parameter, the Reservations API selects only messages that have not yet been delivered or processed successfully.

An example of reasonable use of last_changed would be a server failure causing the loss of reservation data including the booking numbers (reservation IDs). But if the IDs are known, it is more reliable to provide them to the API instead of last_changed.

Typically, you should download and store reservation data, and then present it to the user. It is not necessary to refresh reservations with extra queries. Please report any doubts or concerns to connectivity@booking.com.

Example:

https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?last_change=2012-09-01 00:00:00

Element name: limit

Description: Maximum amount of reservations to return in the request.

Type: integer

Constraints: an integer equal or greater than 10

  • The limit parameter specifies the maximum number of reservations to return in a response. You must use an integer larger than 10. However, note that each response can return less reservations than the specified maximum number regardless of the number of reservations available.

Example:

https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResNotif?limit=200

**Response**

At a higher level, HotelResModifyNotifRQ is a collection of HotelResModifies:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<HotelResModifyNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 HotelResModifyNotifRQ.xsd" TimeStamp="2009-08-24T15:35:21-00:00" Target="Test" Version="1.003" ResStatus="Commit">
   <HotelResModifies>
      <!-- (hotel modification/cancellations, if any) -->
   </HotelResModifies>
</HotelResModifyNotifRQ>

In case the request is for an independent property and you do not have accesss to the property

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResModifyNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelResNotifRS.xsd" TimeStamp="2017-10-12T09:16:43+00:00" Target="Production" Version="2.001">
    <Errors>
        <Error ShortText="Access denied for hotel 56789077"/>
    </Errors>
</OTA_HotelResModifyNotifRS>

In case the request is for multiple properties you will get warning for properties that you do not have access to.

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResModifyNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelResNotifRQ.xsd" TimeStamp="2017-10-12T09:40:42+00:00" Target="Production" Version="2.001">
    <HotelResModifies>
        <!-- (hotel reservations, if any) -->
        <TPA_Extensions>
            <Warnings>
                <Warning Code="497" ShortText="You do not have access to hotel:56789077" Status="NotProcessed" Type="6"/>
                <Warning Code="497" ShortText="You do not have access to hotel:345678" Status="NotProcessed" Type="6"/>
            </Warnings>
        </TPA_Extensions>
    </HotelResModifies>
</OTA_HotelResModifyNotifRQ>

Each modification/cancellation contains:

RoomStays

<RoomStays>
   <RoomStay IndexNumber="697">
      <RoomTypes>
         <!-- ... -->
      </RoomTypes>
      <RatePlans>
         <!-- ... -->
      </RatePlans>
      <RoomRates>
         <!-- ... -->
      </RoomRates>
      <GuestCounts>
         <GuestCount Count="2" />
      </GuestCounts>
      <Total AmountAfterTax="37500" DecimalPlaces="2" CurrencyCode="EUR" />
      <BasicPropertyInfo HotelCode="367456" />
      <ResGuestRPHs>
         <ResGuestRPH RPH="1" />
      </ResGuestRPHs>
      <Comments>
         <!-- ... -->
      </Comments>
      <SpecialRequests>
         <!-- ... -->
      </SpecialRequests>
      <ServiceRPHs>
         <ServiceRPH RPH="1" />
      </ServiceRPHs>
   </RoomStay>
</RoomStays>

RoomStay IndexNumber: the room modification ID as used by BOOKING.COM to identify the booked room within the modification. Unique for every booked room.

RoomTypes

<RoomTypes>
   <RoomType RoomTypeCode="8508109">
      <RoomDescription Name="Test Room 2 - Double Room - Single Use">
         <Text />
         <MealPlan>All meals and select beverages are included in the room rate.</MealPlan>
         <MaxChildren>0</MaxChildren>
      </RoomDescription>
      <AdditionalDetails>
         <AdditionalDetail>
            <DetailDescription>
               <Text>Including service charge</Text>
            </DetailDescription>
         </AdditionalDetail>
         <AdditionalDetail>
            <DetailDescription>
               <Text>Excluding breakfast</Text>
            </DetailDescription>
         </AdditionalDetail>
         <AdditionalDetail>
            <DetailDescription>
               <Text>Including VAT</Text>
            </DetailDescription>
         </AdditionalDetail>
      </AdditionalDetails>
      <Amenities>
         <Amenity>TV</Amenity>
         <Amenity>Telephone</Amenity>
         <Amenity>Toilet</Amenity>
      </Amenities>
   </RoomType>
</RoomTypes>

RoomType RoomTypeCode: the room type ID as used by BOOKING.COM.

RoomDescription Name: Room short name as displayed on the website. Please note that the roomname might differ from the roomname in the roomrates request, depending on the policy and/or rate type. Therefore we suggest to only map based on room ID and rate ID.

RoomDescription Text: Room description as currently known for the booked room in the database.

RoomDescription MealPlan: Mealplan (breakfast, lunch or dinner) information that is applicable for the booked room.

RoomDescription MaxChildren: The static setting of maximum amount of children that can stay free in the booked room. Note that, this does not mean that if the max_children=2, that the guest has entered 2 children in the bookprocess. This is a static setting, defined per room. The maximum age of the children can be found in the policy of the hotel. The hotelier can request this setting with the Booking.com account managers or check in the Booking.com Extranet. AdditionalDetails Text: room info as displayed on the website at the time the modification/cancellation was made.

Amenity: room facility as displayed on the website at the time the modification/cancellation was made.

RatePlans

<RatePlans>
  <RatePlan>
    <Commission>
      <CommissionPayableAmount Amount="69" DecimalPlaces="1" CurrencyCode="EUR" />
    </Commission>
  </RatePlan>
</RatePlans>

Amount: the total commission due for this room for all nights combined.

DecimalPlaces: the number of decimal places for a particular currency (eg. 13350 with DecimalPlaces="2" represents 133.50). CurrencyCode: the currency used for pricing is always the same for the hotel and set by BOOKING.COM.

RoomRates

Price and rate plan ID per night as known at the moment of modification/cancellation.

<RoomRates>
  <RoomRate EffectiveDate="2010-08-31" RatePlanCode="121546">
    <Rates>
      <Rate>
        <Total AmountAfterTax="5000" DecimalPlaces="2" CurrencyCode="EUR" />
      </Rate>
    </Rates>
  </RoomRate>
</RoomRates>

EffectiveDate: effective date.

RatePlanCode: rate plan id.

Virtual credit card (VCC) payments

If you enabled the VCC with rate plan ID feature, you can see the letters VCC attached to the end of the id. This indicates the payment to the property was made with a Booking.com virtual credit card (VCC).

AmountAfterTax/AmountBeforeTax: Specifies the price. If the room has both 'Including VAT' and 'Including taxes' enabled, AmountAfterTax is returned, otherwise AmountBeforeTax.

DecimalPlaces: The number of decimal places for a particular currency (eg. 13350 with DecimalPlaces="2" represents 133.50).

CurrencyCode: the currency used for pricing is always the same for the hotel and set by BOOKING.COM. GuestCounts

<GuestCounts>
  <GuestCount Count="1" />
</GuestCounts>

Count: It is the number of guests for this room as filled by the booker.

Total

The total price for this room for all nights combined, sum of all prices known at the moment of modification/cancellation. Note that there may be some excluded charges from this price. For more details please implement feature include_price_details.

<Total AmountAfterTax="6900" DecimalPlaces="2" CurrencyCode="EUR" />

AmountAfterTax/AmountBeforeTax: Specifies the price. If the room has both 'Including VAT' and 'Including taxes' enabled, AmountAfterTax is returned, otherwise AmountBeforeTax.

DecimalPlaces: The number of decimal places for a particular currency (eg. 13350 with DecimalPlaces="2" represents 133.50).

CurrencyCode: The currency used for pricing is always the same for the hotel and set by BOOKING.COM. BasicPropertyInfo

<BasicPropertyInfo HotelCode="85081" />

HotelCode: the hotel ID as used by BOOKING.COM.

ResGuestRPHs

<ResGuestRPHs>
  <ResGuestRPH RPH="1" />
</ResGuestRPHs>

RPH: Specifies an index number that works as a cross-reference to link guests ([ResGuest]) to rooms [RoomStay].

Comments

<Comments>
   <Comment>
      <Text>I need a wake up service</Text>
   </Comment>
</Comments>
  • Comments Element is not mandatory. It will be included if guest added a comment for the room.

SpecialRequests

<SpecialRequests>
  <SpecialRequest Name="smoking preference">
    <Text>Non-Smoking</Text>
  </SpecialRequest>
</SpecialRequests>
  • SpecialRequests Element is not mandatory. It will be included if guest has special request for the room.

Text: Non-Smoking / Smoking.

ServiceRPHs

<ServiceRPHs>
  <ServiceRPH RPH="1" />
  <ServiceRPH RPH="2" />
</ServiceRPHs>

RPH: Specifies an index number that works as a cross-reference to link guests ([ResGuest]) to rooms [RoomStay].

Services, Service

<Service ServiceRPH="1" ServiceInventoryCode="1" ServicePricingType="4">
  <ServiceDetails>
    <GuestCounts>
      <GuestCount Count="1" />
    </GuestCounts>
    <TimeSpan Duration="1" />
    <Fees>
      <Fee Amount="11" />
    </Fees>
  </ServiceDetails>
</Service>

ServiceRPH: service identification, used to identify the RoomStay

ServiceInventoryCode: the add-on id, according to the table:

ID name
1 Breakfast
2 Continental breakfast
3 American breakfast
4 Buffet breakfast
5 Full english breakfast
6 Lunch
7 Dinner
8 Half board
9 Full board
11 Breakfast for Children
12 Continental breakfast for Children
13 American breakfast for Children
14 Buffet breakfast for Children
15 Full english breakfast for Children
16 Lunch for Children
17 Dinner for Children
18 Half board for Children
19 Full board for Children
20 WiFi
21 Internet
22 Parking space
23 Extrabed
24 Babycot

ServicePricingType: the pricing type code, according to the table:

ID code
0 CPM_NOT_APPLICABLE
1 CPM_PER_STAY
2 CPM_PER_PERSON_PER_STAY
3 CPM_PER_NIGHT
4 CPM_PER_PERSON_PER_NIGHT
5 CPM_PERCENTAGE
6 CPM_PER_PERSON_PER_NIGHT_RESTRICTED

ServiceDetails: The service details, which can include any of these (according to the pricing type code):

  • GuestCount (number of guests)
  • Timespam (number of nights)
  • Fees (price to be paid for the add-ons)

ResGuests, ResGuest

<ResGuest ResGuestRPH="1">
  <Profiles>
    <ProfileInfo>
      <Profile>
        <Customer>
          <PersonName>
            <GivenName>FIRSTNAMEBOOKER</GivenName>
            <Surname>LASTNAMEBOOKER</Surname>
          </PersonName>
        </Customer>
      </Profile>
    </ProfileInfo>
  </Profiles>
</ResGuest>

ResGuestRPH: Specifies an index number that works as a cross-reference to link guests ([ResGuest]) to rooms [RoomStay].

Surname (can be empty): guest name for this room as filled in on the website.

ResGlobalInfo, Guarantee

The credit card information. Will only be sent once and deleted afterwards.

<Guarantee>
  <GuaranteesAccepted>
    <GuaranteeAccepted>
      <PaymentCard CardCode="MC" CardNumber="1234567890123456" SeriesCode="123" ExpireDate="0119" EffectiveDate="2019-01-13" CurrentBalance="10599" DecimalPlaces="2" CurrencyCode="EUR" VCCExpirationDate="2019-01-30">
        <CardHolderName>test</CardHolderName>
      </PaymentCard>
    </GuaranteeAccepted>
  </GuaranteesAccepted>
</Guarantee>

EffectiveDate The date that the card can be charged from. This attribute will exist only for virtual credit cards. To start receiving this attribute, please enable "Reservation virtual credit card activation" feature.

CurrentBalance The current balance that is chargable on the virtual credit card. This attribute will exist only for virtual credit cards. To start receiving this attribute, please enable "Include VCC current balance" feature.

DecimalPlaces This indicates the position of the decimal point (from right to left) in the current balance number. This means that 10599 with DecimalPlaces="2" represents 105.99. To include this attribute to the "PaymentCard" tag, you need to enable the "Include VCC current balance" feature in the Provider Portal.

CurrencyCode This specifies the currency code (ISO 4217) of the virtual credit card's current balance. To include this attribute to the "PaymentCard" tag, you need to enable the "Include VCC current balance" feature in the Provider Portal.

VCCExpirationDate The expiration date of the virtual credit card. This attribute will exist only for virtual credit cards. To start receiving this attribute, please enable "Include VCC expiration full date" feature.

CardCode - 2-character code of the credit card issuer. "XX" is returned if no code for the credit card is defined.

Card Code Description
AX American Express
BC Bank Card
BL Carte Bancaire
BL Carte Bleue
CU Unionpay Credit Card
DN Diners Club
DS Discover Card
JC Japanese Credit Bureau Credit Card
MA Maestro (Switch)
MC Master Card
MI NSPK MIR
VI Visa

CardNumber: credit card number as supplied by the customer. If all 0, something went wrong when retrieving the number (please try again later).

SeriesCode: credit card CVC-code as supplied by the customer. If all 0, something went wrong when retrieving the CVC-code (please try again later).

ExpireDate: credit card expiration date as supplied by the customer. If all 0, something went wrong when retrieving the expiration date (please try again later).

CardHolderName: credit card holder's name as supplied by the customer. If "-", something went wrong when retrieving the holder's name (please try again later).

Total: The total amount of room sales of this modification/cancellation. All rooms * all nights combined. Note that there may be some excluded charges from this price. For more details please implement feature include_price_details.

<Total AmountAfterTax="6900" DecimalPlaces="2" CurrencyCode="EUR" />

AmountAfterTax/AmountBeforeTax: Specifies the price. If the room has both 'Including VAT' and 'Including taxes' enabled, AmountAfterTax is returned, otherwise AmountBeforeTax.

DecimalPlaces: The number of decimal places for a particular currency (eg. 13350 with DecimalPlaces="2" represents 133.50).

CurrencyCode: The currency used for pricing is always the same for the hotel and set by BOOKING.COM. HotelReservationIDs

<HotelReservationIDs>
  <HotelReservationID ResID_Value="223782665" ResID_Date="2010-08-09T11:21:11" />
</HotelReservationIDs>

ResID_Value: Booking.com Reservation ID. ResID_Date: Creation date of the reservation.

Profiles

<Profiles>
  <ProfileInfo>
    <Profile>
      <Customer>
        <PersonName>
          <GivenName>firstnameguest</GivenName>
          <Surname>lastnameguest</Surname>
        </PersonName>
        <Telephone PhoneNumber="123456789" />
        <Email>test.test@booking.com</Email>
        <Address>
          <AddressLine>test</AddressLine>
          <CityName>test</CityName>
          <PostalCode>12345</PostalCode>
          <CountryName Code="NL" />
          <CompanyName />
        </Address>
      </Customer>
    </Profile>
  </ProfileInfo>
</Profiles>

GivenName: first name of the booker as supplied by the customer. Note that this doesn't have to be the same as the guestname(s).

Surname: last name of the booker as supplied by the customer. Note that this doesn't have to be the same as the guestname(s).

PhoneNumber: telephone number as supplied by the customer.

Email: email address supplied by the customer. Used by BOOKING.COM to send the modification/cancellation confirmation.

AddressLine (can be empty): home address supplied by the customer.

CityName (can be empty): city of residence as supplied by the customer.

PostalCode (can be empty): zip / post code as supplied by the customer.

CountryName Code: countrycode of residence as supplied by the customer.

CompanyName (can be empty): company name as supplied by the customer.

RUID strings: The Booking.com responses will always contain a "RUID" string, which is an encoded string used by the Booking.com staff to trace back any updates made before. Whenever the Connectivity Partner wishes the XML-Team to look at any logfiles for debugging or the like; the RUID string needs to be provided. This will enable the Booking.com technical staff to provide Connectivity Partners with support.

Cancellation

In case of cancelation of a room reservation, it won't appear in RoomStays. Also you will get the sum of canelation fees of all canceled rooms in if this sum is not zero.

<Services>
   ...
  <Service>
    <Price>
      <Total AmountAfterTax="120"/>
    </Price>
    <ServiceDetails>
      <Fees>
        <Fee>
          <Description>
            <Text>Cancellation fee</Text>
          </Description>
        </Fee>
      </Fees>
    </ServiceDetails>
  </Service>
   ...
</Services>

Features

These are extra information that can be added to the response. You will have to enable them yourself. To enable Features: From Booking.com connectivity portal go to administration menu and then to feature management

Extra reservation information(res_extra_info)

Reservation extra information will add many new elements to the reservation messages.

  • 1- Highlight genius status of the guest and if they qualify for any available freebies, such as a welcome drink or a late check-out.

  • 2- Facilitating the transmission of payment options such as bank transfer and virtual credit cards.

  • 3- information about the payment of the reservation.

  • 4- Specify whether the booker is traveling on business, including company name and TAX.

 <HotelResModify>
 ...
   <Services>
     <Service ID="5000" Inclusive="True">
       <ServiceDetails>
         <SpecialRequests>
           <SpecialRequest Name="GF_3">
               <Text>Welcome drink</Text>
           </SpecialRequest>
           <SpecialRequest Name="GF_1">
               <Text>Early check in at 12:00</Text>
           </SpecialRequest>
         </SpecialRequests>
       </ServiceDetails>
     </Service>
     <Services>
     ...
     </Service>
   </Services>
   ...
 <HotelResModify>

Services element will also include genius freebies and booking.com’s loyalty program benefits if applicable.

  • Service@ID - "ID=5000" means that the customer has genius freebies or booking.com’s loyalty program benefits.
  • SpecialRequest@Name - represents the Booking.com Service Name Code as outlined below in the BCSN Code table, along with its description in US English in SpecialRequest@Text

BCSN (Booking.com Service Name Codes)

Code Name Description
GF_1 Early check in
GF_2 Free airport shuttle
GF_3 Free drink upon arrival
GF_4 Free bike rental
GF_5 Give Genius guests 2 extra hours to check out
GF_6 Free breakfast
GF_7 Free parking on availability
GF_8 Free Wifi
 <HotelResModify>
   ...
   <RoomStays>
     <RoomStay>
       <RoomRates>
         ...
         <TPA_Extensions>
            <RateRewrite ToCode="70457" FromCode="4681276" FromName="Non Refundable"></RateRewrite>
            <RateGenius Value="true" RateIds="111521"/>
            <BookingCondition>Children and Extra Bed Policy: All children are welcome...</BookingCondition>
         </TPA_Extensions>   
       </RoomRates>
     </RoomStay>
   </RoomStays>
   ...
 </HotelResModify>

If property modified the rate on Booking.com extranet directly then TPA_Extensions element will be included under RoomRates section. RateRewrite is the element that contains attributes: ToCode is the rate that is mapped with the provider. FromCode is the rate code on Booking.com that the rate is originating from. FromName is its respective name on Booking.com RateGenius Element: @Value is true if the rate(s) is genius and the rate(s) code. In the case of multiple nights the @RateIds’s value will be separated by a comma. Genius rates are discounted rates offered to a closed user group who are eligible for this discount provided by the accommodation. * BookingCondition Element: the content of this is what the accommodation has loaded in their policy section.

 <HotelResModify>
   ...
   <ResGlobalInfo>
     ...
     <DepositPayments>
       <GuaranteePayment GuaranteeType="PrePay">
         <Description>
            <Text> Payment via Booking.com Payout type: Booking virtual credit card </Text>
         </Description>
            <AmountPercent Amount="33033" Currency="USD" DecimalPlaces="2"></AmountPercent>
      </GuaranteePayment>
     </DepositPayments>
   <ResGlobalInfo>
   ...
 </HotelResModify>
  • DepositPayments section contains information about the payment of the reservation. Booking.com can take payments from the guest on behalf of the property. In case of no Booking.com managed prepayment, this tag will be omitted.

  • GuaranteePayment@GuaranteeType - has the added types of "Prepay". The Text of the Description will indicate the payout medium: Bank Transfer, or Booking Virtual Credit Card.

The reservation can have two different currency codes

The first one is the hotel default currency. It is the value of the attribute CurrencyCode of the tags <Total> under <ResGlobalInfo> and under <RoomStays>.
The second one is the currency of the booking virtual credit card. That is only in case the payment is payment_on_Booking.com through the Booking Virtual Credit Card. The property can choose through Extranet to recieve the virtual credit card in different curreny than its default one. It is the value of the attribute Currency of the <AmountPercent> tag under <DepositPayments> of the <ResGlobalInfo>.

 <HotelResModify>
   ...
   <TPA_Extension>
     <booker>
        <affiliations>
            <affiliation name="EPS" number="8212355" numbertype="vat" type="company"/>
         </affiliations>
      </booker>
      <flags>
         <flag name="booker_is_genius "/>
         <flag name="no_address_reservation"/>
         <flag name="no_cc_reservation"/>
     </flags>
   </TPA_Extension>
   ...
 <HotelResModify>
  • booker The section contain information about the booker.
  • affiliations Should the booker be on business, you can find more information in the following section.
  • affiliation This section contains information about the name of the corporate company of the guest and VAT /tax if provided.
  • flags Following flags are only included if applicable.
    • booker_is_genius means Booker has a genius status. Genius is a program where Booking.com reward our most frequent bookers by some freebies for a set of properties worldwide. Properties can configure that.
    • no_address_reservation means Booker did not need to provide an address.
    • no_cc_reservation means Booker did not need to provide a credit card.

Include Price Details(include_price_details)

Properties can configure the setup of taxes and charges in the Booking.com extranet. These setups will be reflected on the Front End, confirmation email to the customer and confirmation to the hotel. Properties can specify how VAT + city tax are calculated and can set up to 5 extra charges. You can retrieve these details within the reservation message by allowing this feature.

<Taxes Amount="13350" CurrencyCode="CHF" DecimalPlaces="2">
   <Tax Amount="3988" ChargeFrequency="12" Code="" CurrencyCode="CHF" DecimalPlaces="2" Type="Inclusive">
      <TaxDescription><Text>VAT (3.8%)</Text></TaxDescription>
   </Tax>
   ...
</Taxes>
  • Taxes This section will have all taxes and charges added by thr ptoperty from Booking.com extranet. it can contain up to 5 Tax child elements
  • Taxes@Amout Total amount of taxes.
  • Taxes@CurrencyCode Currency Code of the total amount of taxes.
  • Taxes@DecimalPlaces the number of decimal places for a particular currency (eg. 13350 with DecimalPlaces="2" represents 133.50).
  • Tax this section will contain the details of certain Tax detail.
  • Tax@Amount the amount of the tax.
  • Tax@ChargeFrequency This attribute shows whether the tax is per person or per night. Check ChargeFrequency table below for different cases.
  • Tax@Code OTA code for taxes/extra charges types.If there is no matching code, it will be filled with the description of the tax. Check TaxCode table below.
  • Taxe@CurrencyCode Currency Code of the amount of taxe.
  • Taxes@DecimalPlaces the number of decimal places for a particular currency (eg. 13350 with DecimalPlaces="2" represents 133.50).
  • Taxe@type indicate whether this amount is included in the total price of the reservation or not.

ChargeFrequency codes table:

ChargeFrequency Code Description
21 per person and per night
20 per person only
19 per nights only
12 niether per person nor per night

TaxCode table:

Tax Code Description
14 service charge
19 or 36 Value Added Tax (VAT)
3 City Tax
17 or 13 Tax
46 Government Tax

OTA hotel reservation response token(ota_res_response_token)

It has been reported by some providers that sometimes they are not able to pick up reservation modifications when they're in the process of sending a response regarding a previous message (either a confirmation or another modification). This results in inconsistent data for the hotels and possibly a poor experience for the guests. This is due to a limitation of our system, making it prone to race conditions like that. We have fixed it by implementing a simple Optimistic Concurrency Control mechanism. With this mechanism, it is now necessary to always include a token in OTA responses. They identify which message the provider is replying to, so we can properly acknowledge that a message has been received by the provider. We'll include a new HotelReservationID tag for every reservation. This tag is differentiated by having ResID_Source="BOOKING.COM" and ResID_Type="18". ResID_Value contains the response token that needs to be sent back to us in the OTA responses. Below you can see an example of the new tag, alongside the one that contains the reservation number.

<HotelReservationIDs>
  <HotelReservationID ResID_Value="312637549" ResID_Date="2012-11-13T11:06:39" />
  <HotelReservationID ResID_Value="c6cc660e" ResID_Source="BOOKING.COM" ResID_Type="18" />
</HotelReservationIDs>

In the OTA responses, this tag just needs to be added as-is inside HotelReservationIDs. Like that:

<HotelReservationIDs>
   <HotelReservationID ResID_Value="812864414" ResID_Source="BOOKING.COM" ResID_Type="14" />
   <HotelReservationID ResID_Value="OWNCODE64143566" ResID_Source="RT" ResID_Type="14" />
   <HotelReservationID ResID_Value="c6cc660e" ResID_Source="BOOKING.COM" ResID_Type="18" />
</HotelReservationIDs>

By Adding this info in the response we will detect there is a race condition happened and will return an HTTP status code "409 Conflict", and a message "response token '...' for hotel reservation '...' does not match. please pull again."

Include reservation-level guest count(childcount)

Include Number of adults and children (with their ages) that the booker searched for when making the booking along with the reservation message.

NOTE This is not guaranteed to match the number of guests that arrive. The total number of adults should still be less than or equal to the max occupancy allowed for adults for the rooms reserved.

<HotelResModifies>
    <HotelResModify>
         ...
        <ResGlobalInfo>
            ...
            <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="2"/>
                <GuestCount Age="6" AgeQualifyingCode="8" Count="1"/>
                <GuestCount Age="10" AgeQualifyingCode="8" Count="1"/>
            </GuestCounts>
        </ResGlobalInfo>
    </HotelResModify>
</HotelResModifies>

GuestCounts This section will contain all guest counts.

  • GuestCount Element minimum occurence = 0.

  • GuestCount@AgeQualifyingCode this is the code which identify whether the count is for children or adults. if adults Atrribute Age will not be included. It can has 2 values. 10 means counted as adults. 8 means counted as children.

  • GuestCount@Age If AgeQualifyingCode attribute = 8 then you will find this attribute which shows the age of the children.

Include total commision(include_total_commission)

Include total commission of the reservation.

Currently commission amount is displayed per each RoomStay. As you know one reservation can have multiple Room stays. By enabling this feature you will get the total commission amount for the reservation.

This is very important for modification/cancellation messages to check the commission amount calculated, as some non-refundable reservations may be obligable for commission.

<HotelResModifyNotifRQ>
   <HotelResModifies>
      <HotelResModify>
       ...
         <ResGlobalInfo>
            ...
            <TotalCommissions>
                <CommissionPayableAmount Amount="69" DecimalPlaces="1" CurrencyCode="EUR" />
                <Comment>This is the total commission amount calculated by Booking.com</Comment>
            </TotalCommissions>
         </ResGlobalInfo>
      </HotelResModify>
   </HotelResModifies>
</HotelResModifyNotifRQ>

Amount: the total commission due for this reservation for all rooms for all nights combined.

DecimalPlaces: the number of decimal places for a particular currency (eg. 6909 with DecimalPlaces="1" represents 690.9). CurrencyCode: the currency used for pricing is always the same for the hotel and set by BOOKING.COM.

Timestamp of last update for reservation (res_modify_timestamp)

Modified Reservations will contain timestamp of modification. Until recently xml message of reservation only included timestamp of when reservation was made, in OTA (eg: ResID_Date="2016-09-13T09:08:28") When reservation is modified the timestamp does not change as it designates creation of reservation. To establish timestamp of modification, until recently, providers had to keep a record of when modification was retrieved.

<HotelResModify LastModifyDateTime="2016-09-01T09:35:42+00:00"&gt;

Include room-level occupancy (include_room_level_occupancy)

This feature when enabled will return maximum occupancy for each room reservation. If the room has rate level restrictions then this is the maximum occupancy for that rate. In case of no rate level restrictions this is the maximum occupancy of the room. It can be used to get the maximum occupancy of the room for a price.

<RoomStays>
   <RoomStay IndexNumber="697">
      <TPA_Extensions>
         <Occupancy>2</Occupancy>
      </TPA_Extensions>
   </RoomStay>
</RoomStays>

Add cancellation policy (res_cancel_policies)

This feature adds:

1- The policy code which describes what are the cancellation policies 2- Grace period information for non-refundable rooms. If a property chooses to offer a grace period guests can cancel non-refundable bookings within 1, 4 or 24 hours after booking. 3- Add Grace period to ResGlobalInfo.Comments

Normally there will be the cancel penalty element with the policy code. Only if the grace period policy applies there will be another element with policy code "grace_period" and the deadline. Amount attribute will always be 100 incase of grace_period and means that cancellation is free of charge within the specified deadline.

Note: for cancellation policy details (including the actual amount needs to be paid and dates) please check feature "add cancellation policy details"

<RoomStays>
   <RoomStay IndexNumber="697">
      ...
      <CancelPenalties&gt;
          <CancelPenalty PolicyCode="1" /&gt;
          <CancelPenalty PolicyCode="grace_period"&gt;
              <Deadline Time="2017-02-20T14:32:10+00:00" /&gt;
              <AmountPercent Amount="100" /&gt;
          </CancelPenalty&gt;
      </CancelPenalties&gt;
   </RoomStay>
</RoomStays>
FIELD DESCRIPTION TYPE OCCURRENCES
CancelPenalties This is the parent element for all cancel penality policies object 1..1
CancelPenalty - object 0..*
CancelPenalty[@PolicyCode] Cancellation policy code. It will either has the policy code for the room reservation rate which is an integer or "grace_period" for the grace period policy if applies string 1..1
Deadline This element will indicate when this policy ends object 0..1
Deadline[@time] This attribute will indicate when this policy ends. The timezone is indicated in the value datetime with the timezone 1..1
AmountPercent This element will how much the property should charge the guest, if the guest cancelled before the deadline object 0..1
AmountPercent[@amount] This attribute is the amount that the property should charge the guest if the guest cancelled before the deadline. Amount attribute will always be 100 incase of grace_period and means that cancellation is free of charge within the specified deadline Integer 1..1

Add cancellation policy details (res_cancel_policy_details)

Note: You should implement feature "add cancellation policy" first.

This feature add cancellation policy timeline including: 1- Start and end of cancellation policy periods. ex: from date x to date y if guest cancelled he will be charged z amount 2- The exact amount that the guest should be charged if he cancelled the reservation

<RoomStays>
   <RoomStay IndexNumber="697">
      ...
      <CancelPenalties&gt;
          <CancelPenalty PolicyCode="68" From="2018-04-21T21:34:33+00:00" Until="2018-07-16T21:59:00+00:00"&gt;
              <AmountPercent Amount="0" DecimalPlaces="2" CurrencyCode="EUR" /&gt;
          </CancelPenalty&gt;
          <CancelPenalty PolicyCode="68" From="2018-07-16T22:00:00+00:00"&gt;
              <AmountPercent Amount="17000" DecimalPlaces="2" CurrencyCode="EUR" /&gt;
          </CancelPenalty&gt;
      </CancelPenalties&gt;
   </RoomStay>
</RoomStays>
FIELD DESCRIPTION TYPE OCCURRENCES
CancelPenalties This is the parent element for all cancel penality policies object 1..1
CancelPenalty - object 0..*
CancelPenalty[@PolicyCode] Cancellation policy code. It will either has the policy code for the room reservation rate which is an integer or "grace_period" for the grace period policy if applies string 1..1
CancelPenalty[@From] Starting time of this policy datetime with the timezone 0..1
CancelPenalty[@Until] End time of this policy. When their is no Until time specified and it is not a grace_period. Then this policy applies until forever datetime with the timezone 0..1
AmountPercent This element will how much the property should charge the guest, if the guest cancelled before the deadline object 0..1
AmountPercent[@Amount] This attribute is the amount that the property should charge the guest if the guest cancelled before the deadline. Amount attribute will always be 100 incase of grace_period and means that cancellation is free of charge within the specified deadline Integer 1..1
AmountPercent[@DecimalPlaces] Decimal places for the amount Integer 0..1
AmountPercent[@CurrencyCode] Currency code for the amount string 0..1

Error codes

You may receive errors in the response from Booking.com. Below a list of OTA error codes that can occur.

OTA Error Code Description
367 Not processed. Invalid value or incorrect combination of tags
321 Missing element