Last updated

Retrieving modified/cancelled reservations

Modified or cancelled reservation message implies that there were changes to the reservation after you have acknowledged the original reservation message. However, if there were changes to the reservation before you could acknowledge the original new reservation message, then you can still retrieve the reservation as a new reservation message.

To process modified or cancelled reservations using OTA specifications:

  1. Retrieve the modified or cancelled reservations, and,
  2. Acknowledge that you have processed the reservations.

To retrieve modified or cancelled reservations

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

Use the OTA_HotelResModifyNotif endpoint to get all the modified or cancelled property reservations made through the Booking.com channels.

To ensure timely delivery of data, call GET OTA_HotelResModifyNotif once per twenty seconds. However, to help ensure that acknowledgements have been processed, wait five seconds between POST OTA_HotelResModifyNotif and the next GET OTA_HotelResModifyNotif.

Similar to new reservations, you can apply filters to retrieve:

  • A single reservation.
  • Reservations specific to certain properties specified by property IDs.
  • Reservations made since a specified date.
  • A maximum number of reservations to return per call.

Query parameters

The following table describes the optional elements you can add as query parameters to filter the incoming reservations.

Use filters sparingly

To process reservations optimally, Booking.com recommends that you use these parameters sparingly and only while retrieving reservations immediately after an unexpected outage. Make sure to remove these parameters after recovering from unexpected events.

ElementDescriptionTypeRequired/OptionalNotes
idSpecify a reservation ID to retrieve a single reservation.integeroptionalSpecify a reservation ID that you have already retrieved. For accurate results, use the hotel_ids parameter and specify the property ID. With this parameter, you may access reservations made more than two weeks in the past.
Use the OTA_HotelResModifyNotif endpoint for reservations that have been modified or cancelled and OTA_HotelResNotif for all other reservations.
For example, https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResNotif?id=2672953870&hotel_ids=8011855
hotel_idsSpecify the unique property ID(s), separated by comma, to limit results to those properties. You can specify, for example, 10 property IDs.integeroptionalUse only comma separated property IDs to specify individual property ID values. When retrieving reservations for multiple properties using this parameter, if you do not have access to some properties, the API returns a Warning in the response only for those properties while returning reservations for all other properties that you have access to. Use this parameter to restrict the results to a given property.
For example, when servicing an interactive request, you may pass hotel_ids for the partner account and id from an input field. If they do not match, the API returns 404 status. For example, https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResNotif?id=2672953870&hotel_ids=8011855
last_change[Only applicable when Reservations Recovery API is not implemented] Specify a date, in the format YYYY-MM-DD HH:MM:SS, to retrieve all reservations that were created, modified or cancelled since the specified date. You can request reservations up until 2 weeks in the past.datetimeoptionalUsing this filter, the API returns reservations starting from the oldest reservation. You can limit the returned reservations count by specifying the limit parameter.
Use this parameter only when recovering lost reservations after an unexpected outage. Specifying a future date and time returns 0 reservations.
Using this filter immediately after a daylight-savings time change may return 0 or more reservations depending on whether the clock was set ahead or behind.
Important: Using this filter when the feature: Enable Reservation Recovery API (enable_reservation_recovery_api) is turned on, returns a HTTP 400 error.
limitSpecify a maximum number of reservations to return. Specify a value >=10 and <= 200.integeroptionalThe API may return reservations less than the specified limit based on the immediate availability of data, even if there are enough reservations to satisfy the limit. This filter can improve latency at the expense of throughput, therefore it adds a risk of a throughput bottleneck. It is not recommended to use a low value when retrieving new bookings and modifications.

Query parameter example

The following query retrieves modified or cancelled reservation(s) for property with ID 8011855 that were made since 2025-03-31 11:00:00. The query pulls 200 results per call, in case the result set runs longer than that.


GET https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif?hotel_ids=8011855&last_change=2025-03-31+11%3A00%3A00&limit=200

Response body example

The following is a successful response body example:

<?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_HotelResModifyNotifRQ.xsd" TimeStamp="2022-03-24T16:05:05+00:00" Target="Production" Version="2.001">
    <HotelResModifies>
        <HotelResModify>
            <RoomStays>
                <RoomStay IndexNumber="167">
                    <RoomTypes>
                        <RoomType RoomTypeCode="801185504">
                            <RoomDescription Name="Quadruple Room - General - Breakfast included">
                                <Text>Rooms are 13 square metres.</Text>
                                <MealPlan>Breakfast is included in the room rate.</MealPlan>
                                <MaxChildren>0</MaxChildren>
                            </RoomDescription>
                        </RoomType>
                    </RoomTypes>
                    <RatePlans>
                        <RatePlan>
                            <Commission>
                                <CommissionPayableAmount Amount="1128" DecimalPlaces="2" CurrencyCode="EUR"/>
                            </Commission>
                        </RatePlan>
                    </RatePlans>
                    <RoomRates>
                        <RoomRate EffectiveDate="2022-04-11" RatePlanCode="25278032">
                            <Rates>
                                <Rate>
                                    <Total AmountAfterTax="2000" DecimalPlaces="2" CurrencyCode="EUR" />
                                </Rate>
                            </Rates>
                        </RoomRate>
                        <RoomRate EffectiveDate="2022-04-12" RatePlanCode="25278032">
                            <Rates>
                                <Rate>
                                    <Total AmountAfterTax="2000" DecimalPlaces="2" CurrencyCode="EUR" />
                                </Rate>
                            </Rates>
                        </RoomRate>
                        <RoomRate EffectiveDate="2022-04-13" RatePlanCode="25278032">
                            <Rates>
                                <Rate>
                                    <Total AmountAfterTax="2000" DecimalPlaces="2" CurrencyCode="EUR" />
                                </Rate>
                            </Rates>
                        </RoomRate>
                    </RoomRates>
                    <GuestCounts>
                        <GuestCount Count="2"/>
                    </GuestCounts>
                    <Total AmountAfterTax="6000" DecimalPlaces="2" CurrencyCode="EUR"></Total>
                    <BasicPropertyInfo HotelCode="8011855"/>
                    <ResGuestRPHs>
                        <ResGuestRPH RPH="1"/>
                    </ResGuestRPHs>
                    <SpecialRequests>
                        <SpecialRequest Name="smoking preference">
                            <Text>Non-Smoking</Text>
                        </SpecialRequest>
                    </SpecialRequests>
                </RoomStay>
            </RoomStays>
            <ResGuests>
                <ResGuest ResGuestRPH="1">
                    <Profiles>
                        <ProfileInfo>
                            <Profile>
                                <Customer>
                                    <PersonName>
                                        <Surname>Dory B</Surname>
                                    </PersonName>
                                </Customer>
                            </Profile>
                        </ProfileInfo>
                    </Profiles>
                </ResGuest>
            </ResGuests>
            <ResGlobalInfo>
                <Comments>
                    <Comment ParagraphNumber="1">
                        <Text>** Genius Booker **</Text>
                    </Comment>
                </Comments>
                <Total AmountAfterTax="6000" DecimalPlaces="2" CurrencyCode="EUR" />
                <HotelReservationIDs>
                    <HotelReservationID ResID_Value="2254083207" ResID_Date="2022-03-24T16:01:39"/>
                </HotelReservationIDs>
                <Profiles>
                    <ProfileInfo>
                        <Profile>
                            <Customer>
                                <PersonName>
                                    <GivenName>Dory</GivenName>
                                    <Surname>B</Surname>
                                </PersonName>
                                <Address>
                                    <AddressLine></AddressLine>
                                    <CityName></CityName>
                                    <PostalCode></PostalCode>
                                    <CountryName Code="NL" />
                                    <CompanyName></CompanyName>
                                </Address>
                            </Customer>
                        </Profile>
                    </ProfileInfo>
                </Profiles>
            </ResGlobalInfo>
        </HotelResModify>
    </HotelResModifies>
</OTA_HotelResModifyNotifRQ>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9Yesl4MHBAMOxcc2yCMFSrdKRHoNVTchP8eldx3ay2yvH8nRb31Y2KdiMxiChLmBDukzMBLVYHXZx2ZEHX60KCos=] -->

Response body elements

To better understand each response element that make up the response body, this section is split into multiple tables.

The response body contains the following high-level root elements:

Reservation details

ElementAttributeDescriptionTypeNotes
OTA_HotelResModifyNotifRQContains the response data.object
>HotelResModifiesContains the modified/cancelled property reservations for each specified property.object
>>HotelResModifyContains individual property reservation details that were modified/cancelled.object
>>> RoomStaysContains the booked room details per reservation.object
>>> ServicesContains details of services that the guest is eligible for.objectTo view this and its child elements, make sure to enable the feature: Get extra information for reservations (res_extra_info).

Booked room details

The following table lists all the elements that consolidate details per booked room.

ElementAttributeDescriptionTypeNotes
RoomStayContains the room reservation details for each booked room.objectThe details include Booking.com room type, rate plan, commission payable, guest count, and reference to guest details among others.
IndexNumberSpecifies a unique ID generated by Booking.com for each booked room in the reservation.integerUse this ID to identify the booked room within the reservation. Unique for every booked room.
> RoomTypesContains the room type details for each booked room.object
>> RoomTypeContains the individual room type details for each reservation.object
RoomTypeCodeSpecifies the unique room type ID generated by Booking.com at the time of creating the room type.integer
>>> RoomDescriptionContains a description of the booked room.object
NameSpecifies the room name for the booked room.stringBooking.com generates the name from the following values: room name, cancellation policy and meal plan name.
>>>> TextSpecifies the room description for the booked room.stringBooking.com populates this field based on the property’s settings in the room amenity and room details. Note that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint.
>>>> MealPlanSpecifies the meal plan information applicable for the booked room.stringNote that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint.
>>>> MaxChildrenSpecifies the maximum number of children who can stay in the booked room for free.integerThis is a static setting defined per room when you set up Children Policies. Guests cannot specify a value for the MaxChildren attribute during the booking process. The maximum age of the children can be found in the policy of the property. The property can request this setting through the Booking.com Connectivity Support team or check in the Booking.com Extranet.
>>> AmenitiesContains the details of all the facilities available in the room and at the property at the time of reservation.object
>>>> AmenitySpecifies the details of each facility available in the room and at the property at the time of reservation.stringNote that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint.
> RatePlansContains the rate plan information for the reservation.object
>> RatePlanContains individual rate plan information for the reservation.object
>>> CommissionContains the commission information for each reservation that the property owes to Booking.com.object
>>>> CommissionPayableAmountContains the individual commission information.object
AmountCaptures the total commission due for this room for all nights combined.integer
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integerFor example, Amount=13350 with DecimalPlaces="2" represents 133.50.
CurrencyCodeSpecifies the currency used for pricing the commission.enumerated stringThis is always the same for a property and is set by Booking.com.
> RoomRatesContains the room price and rate plan information.object
>> RoomRateContains individual room price and rate plan information.object
EffectiveDateSpecifies the start date of the stay.datetime
RatePlanCodeSpecifies the unique rate plan code generated by Booking.com at the time of creating the rate plan.integer
>>> RatesContains room rate information.object
>>>> RateContains individual room rate information.object
>>>>> TotalContains information about the total price.object
AmountAfterTax/AmountBeforeTaxSpecifies the total price including all relevant taxes.integerIf the property has both Including VAT and Including taxes enabled in the Extranet (VAT/Tax/Charges page under the Property tab), the API returns AmountAfterTax, otherwise it returns AmountBeforeTax.
CurrencyCodeSpecifies the currency used for pricing.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integerFor example, Amount=13350 with DecimalPlaces="2" represents 133.50.
>> TPA_ExtensionsContains additional reservation details for each booked room.objectTo see this and GuestCounts element, you must enable the feature: Include room-level guest count old (childcount_per_room). To see this and the rate rewrite information, you must enable the feature: Get extra information for reservations (res_extra_info).
> OccupancyContains the maximum occupancy for each room reservation. If the room has rate level restrictions, then this is the maximum occupancy for that rate.integerTo see this element, make sure to enable the feature: Include room-level occupancy (include_room_level_occupancy).
> GuestCountsContains the room-level guest count for the reservation.object
>> GuestCountContains the guest count for the reservation.object
CountSpecifies the number of guests for this reservation as entered by the booker.integer
AgeQualifyingCodeSpecifies a code that represents the guest's age. Each code represents an age range.integerTo see this and the age attribute, you must enable the feature: Include room-level guest count (guestcount_per_room).
The supported codes are:
10 - Adult.
8 - Child.
AgeSpecifies the age of the child guests.integerOnly available when the AgeQualifyingCode = 8.
> CancelPenaltiesContains the cancellation policy assigned to the roomrate.objectTo see this and its child elements, make sure to enable the feature: Add cancellation policy (res_cancel_policies).
> TotalContains the total price for this room for all nights combined. Calculated as the sum of all prices known at the moment of reservation.objectFor a detailed breakdown of individual taxes and fees for the booking, use the Payments Clarity Package V2 feature. We no longer recommend using the Include price details (include_price_details) feature.
AmountAfterTax/AmountBeforeTaxSpecifies the total price including all the taxes.integerIf the property has both Including VAT and Including taxes enabled, AmountAfterTax is returned, otherwise AmountBeforeTax.
CurrencyCodeSpecifies the currency used for pricing.enumerated stringThis is always the same for a property and is set by Booking.com
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integerFor example, Amount=13350 with DecimalPlaces="2" represents 133.50.
>> TaxesContains the tax information.objectFor a detailed breakdown of individual taxes and fees for the booking, use the Payments Clarity Package V2 feature. We no longer recommend using the Include price details (include_price_details) feature.
> BasicPropertyInfoContains the property information where the room is booked.object
HotelCodeSpecifies the property ID as used by Booking.com.integer
> ResGuestRPHsContains an index number that works as a cross-reference to link guests (ResGuest) to rooms (RoomStay).object
>> ResGuestRPHobject
RPHSpecifies an index number that works as a cross-reference to link guests (ResGuest) to rooms (RoomStay).integer
> SpecialRequestsContains any special requests selected by the guest.objectTo view this and the child elements, make sure to enable the feature: Get extra information for reservations (res_extra_info).
>> SpecialRequestContains individual special requestsobject
NameSpecifies the service code.enumerated stringFor a full list of all available service names, see Service names/codes.
>>> TextSpecifies the service descriptionenumerated stringFor a full list of all the available service descriptions, see Service names.

Guest details

The following table lists all the elements that capture guest details.

ElementAttributeDescriptionTypeNotes
ResGuestsContains the details of all the guests for the reservation.object
> ResGuestContains individual guest details per room booked in the reservation.object
ResGuestRPHSpecifies a reference to the RPH attribute under RoomStay > ResGuestRPH.integerUse this value to identify the room type details that this guest is assigned to.
>> ProfilesContains a collection of guest details.object
>>> ProfileInfoContains a collection of individual guest details.object
>>>> ProfileContains individual guest details.objectUseful when there is more than one room booked to list guest details for each room.
>>>>> CustomerContains the guest details.object
>>>>>> PersonNameContains the first name and surname of the guest.objectThis can be different from the booker name.
>>>>>>> GivenNameSpecifies the first name of the booker as filled by the booker.stringOnly visible when the feature: Split Surname and GivenName (ota_res_split_names) is enabled. The API splits the name into a given name and surname. Otherwise, this field is omitted.
>>>>>>> SurnameContains the guest name for this room as filled in on the website.stringIf the feature: Split Surname and GivenName (ota_res_split_names) is enabled, then this element contains only the surname of the guest. Otherwise, it specifies both the given name and surname.
TPA_ExtensionsContains additional reservation details about the guest.objectTo view this and its child elements, make sure to enable the feature: Get extra information for reservations (res_extra_info).

Booker details

The following table lists all the elements that capture details of the person who booked the stay.

If you enable the feature: Include dummy CC details for bank transfer payout (res_dummy_cc_on_bt), the API returns dummy credit card details in reservation messages when:

  • Guests pay through an alternate payment method.
  • The property's payout method is set to bank transfer.

You can identify that a message has dummy credit card details by looking for <CardHolderName>NOCCRESERVATION</CardHolderName>. For more details, see Include dummy credit card details for bank transfer payout.

ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains more details on the reservation.objectThis includes comments, reservation ID, and details of the individual who made the reservation.
> CommentsContains all the comments about the reservation provided at the time of booking.object
> GuaranteeContains the card details as a guarantee for the reservation.object
>> GuaranteesAcceptedobject
>>> GuaranteeAcceptedobject
>>>> PaymentCardobject
CardCodeSpecifies the 2-character code of the credit card issuer.enumerated stringThe API returns "XX" if no code for the credit card is defined. Only returns from one of the values in the Card code table.
CardNumberSpecifies the credit card number as supplied by the guest.stringIf all values are 0s, something went wrong when retrieving the number. You can try retrieving the reservation again.
SeriesCodeSpecifies the credit card CVC code as supplied by the guest.stringIf all values are 0s, something went wrong when retrieving the CVC-code. You can try retrieving the reservation again.
ExpireDateSpecifies the credit card expiration date as supplied by the guest.datetimeIf all values are 0s, something went wrong when retrieving the expiration date. You can try retrieving the reservation again.
EffectiveDateSpecifies the date that the card can be charged from.datetimeApplicable only for Payments by Booking reservations and when the payout type is virtual credit card.
This attribute is included in the response, only when the Payments Clarity Package V2 (payment_clarity_package_v2) feature is enabled. To enable/disable this feature, contact Connectivity Support.
We no longer recommend using the Payments Clarity Package(vcc_payment_v2) feature.
CurrentBalanceSpecifies the current balance that is chargeable on the virtual credit card.integerApplicable only for Payments by Booking reservations and when the payout type is virtual credit card.
This attribute is included in the response, only when the Payments Clarity Package V2 (payment_clarity_package_v2) feature is enabled. To enable/disable this feature, contact Connectivity Support.
We no longer recommend using the Payments Clarity Package(vcc_payment_v2) feature.
DecimalPlacesSpecifies the position of the decimal point (from right to left) in the current balance value.integerFor example, Amount=10599 with DecimalPlaces="2" represents 105.99.
This attribute is included in the response, only when the Payments Clarity Package V2 (payment_clarity_package_v2) feature is enabled. To enable/disable this feature, contact Connectivity Support.
We no longer recommend using the Payments Clarity Package(vcc_payment_v2) feature.
CurrencyCodeSpecifies the currency code (ISO 4217) of the virtual credit card's current balance.string
This attribute is included in the response, only when the Payments Clarity Package V2 (payment_clarity_package_v2) feature is enabled. To enable/disable this feature, contact Connectivity Support.
We no longer recommend using the Payments Clarity Package(vcc_payment_v2) feature.
VCCExpirationDateSpecifies the expiration date of the virtual credit card.stringApplicable only for Payments by Booking reservations and when the payout type is virtual credit card.
This attribute is included in the response, only when the Payments Clarity Package V2(payment_clarity_package_v2) feature is enabled. To enable/disable this feature, contact Connectivity Support.
We no longer recommend using the Payments Clarity Package(vcc_payment_v2) feature.
>>>>>>>> CardHolderNameSpecifies the credit card holder's name as supplied by the guest.objectIf you receive "-" as the value, then something went wrong when retrieving the holder's name. You can try retrieving the reservation again.
If the API returns NOCCRESERVATION, then the reservation message contains dummy credit card details.
> TotalSpecifies the total amount of room sales of this reservation.objectComputed as (all rooms * all nights combined). For a detailed breakdown of individual taxes and fees for the booking, use the Payments Clarity Package V2 feature. We no longer recommend using the Include price details (include_price_details) feature.
AmountAfterTax/AmountBeforeTaxSpecifies the total price including taxes.integerIf the property has VAT set as included in the price, then the API returns AmountAfterTax, otherwise it returns AmountBeforeTax.
CurrencyCodeSpecifies the currency used for pricing.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integerFor example, Amount=13350 with DecimalPlaces="2" represents 133.50.
> HotelReservationIDsContains the reservationsobjectTo view the ResID_Source and ResID_Type child elements, enable the feature: OTA hotel reservation response token (ota_res_response_token).
> HotelReservationIDContains individual reservations message ID.object
ResID_ValueSpecifies the Booking.com reservation ID.string
ResID_DateSpecifies the reservation creation date and time value.datetime
> ProfilesContains booker details.object
>> ProfileInfoobject
>>> Profileobject
>>>> CustomerContains details about the booker.object
LanguageSpecifies the customer's preferred language of communication with the property.string
This attribute is included in the response, only when the Include Preferred language in Customer (res_customer_preferred_lang)feature is enabled. To enable/disable this feature, contact Connectivity Support.
>>>>> PersonNameContains the booker's personal details such as name, phone number and address.object
>>>>>> GivenNameSpecifies the first name of the booker as filled by the booker on the website.objectNote that this doesn't have to be the same as the guest name(s).
>>>>>> SurnameSpecifies the last name of the booker as filled by the booker on the website.objectNote that this doesn't have to be the same as the guest name(s).
>>>>> TelephoneContains the telephone number details.object
PhoneNumberSpecifies the telephone number as supplied by the booker.string
>>>>> EmailSpecifies the email address supplied by the booker.objectUsed by Booking.com to send the reservation confirmation.
>>>>> AddressContains the home address details.object
>>>>>> AddressLineSpecifies the home address supplied by the booker.object
>>>>>> CityNameSpecifies the city of residence as supplied by the booker.object
>>>>>> PostalCodeSpecifies the zip / post code as supplied by the booker.object
>>>>>> CountryNameSpecifies the country code of residence as supplied by the booker.object
CodeSpecifies the country code of residence as supplied by the booker.string
>>>>>> CompanyNameSpecifies the company name as supplied by the booker.object
> TotalCommissionsContains commission details for all rooms in a reservation.objectTo view this and its child elements, make sure to enable the feature: Include total commission (include_total_commission).
> DepositPaymentsobjectTo view this and its child elements, make sure to enable the feature: Get extra information for reservations (res_extra_info).
RUIDSpecifies the unique request ID which is an encoded string.objectYou can share this ID with the Booking.com Connectivity Support team when you run into an issue. This can help in understanding what went wrong.

Include room-level guest counts (old)

When you enable the feature: Include room-level guest count old (childcount_per_room), the API returns the number of adults and children per room in the reservation along with age information.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> TPA_ExtensionsContains additional reservation details for each booked room.object
>>> GuestCountsContains the number of adults and children per each room in the reservation.object
>>>> GuestCountContains the number of adults and children per room in the reservation.object
AgeQualifyingCodeSpecifies a code that represents the guest's age. Each code represents an age range.integerThe supported codes are:
10 - Adult.
8 - Child.
CountSpecifies the guest count.integer
AgeSpecifies the age of the child guests.integerOnly available when the AgeQualifyingCode = 8.

Include room-level guest count

When you enable the feature: Include room-level guest count (guestcount_per_room), the API returns the number of adults and children per room in the reservation along with age information.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> GuestCountsContains the number of adults and children per each room in the reservation.object
>>> GuestCountContains the number of adults and children per room in the reservation.object
AgeQualifyingCodeSpecifies a code that represents the guest's age. Each code represents an age range.integerThe supported codes are:
10 - Adult.
8 - Child.
CountSpecifies the guest count.integer
AgeSpecifies the age of the child guests.integerOnly available when the AgeQualifyingCode = 8.

Include room-level occupancy

When you enable the feature: Include room-level occupancy (include_room_level_occupancy), the API returns the 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, then this is the maximum occupancy of the room. It can be used to get the maximum occupancy of the room for a price.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> OccupancyContains the maximum occupancy for each room reservation. If the room has rate level restrictions, then this is the maximum occupancy for that rate.integer

Add cancellation policy

When you enable the feature: Add cancellation policy (res_cancel_policies), you can view the cancellation policy assigned to the roomrate.

The API also shows grace period information, if applicable. A grace period is a pre-defined period of time that allows guests to change a booking without being penalised with a fee. For more information, see how to set up grace period functionality.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> CancelPenaltiesContains the cancellation penalty details.object
>>> CancelPenaltyContains the Booking.com cancellation policy code and its effective date.object
PolicyCodeSpecifies the Booking.com cancellation policy code.integerIf the grace period policy exception applies, the API specifies another element with policy code grace_period and the deadline of the grace period.
>>>> DeadlineIndicates when the grace period ends.objectApplicable only when the grace period policy exception is in place.
TimeIndicates when the grace period ends.datetimeApplicable only when the grace period policy exception is in place.
>>>> AmountPercentContains the penalty amount.object
AmountSpecifies the cancellation fee (if applicable) expressed as a fixed amount, if the guests cancels the booking.integerWhen a grace period policy exception is in place, the value will always be 100, that is, the guest is charged 100% when they cancel the booking after the grace period.

Add cancellation policy details

When you enable the feature: Add cancellation policy details (res_cancel_policy_details), you can view the cancellation policy details assigned to the roomrate.

The API also shows grace period information, if applicable. A grace period is a pre-defined period of time that allows guests to change a booking without being penalised with a fee. For more information, see how to set up grace period functionality.

Note: You must implement feature Add cancellation policy first.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> CancelPenaltiesContains the cancellation penalty details.object
>>> CancelPenaltyContains the Booking.com cancellation policy code and its effective date.object
PolicyCodeSpecifies the Booking.com cancellation policy code.integerIf the grace period policy exception applies, the API specifies another element with policy code grace_period.
FromSpecifies the start date and time from which the policy is in effect.datetimeNot applicable for grace period policy exception.
UntilSpecifies the date and time until which the policy is in effect.datetimeApplicable only when the policy has an end date.
Not applicable for grace period policy exception.
>>>> DeadlineIndicates when the grace period policy ends.objectApplicable only when the grace period policy exception is in place.
TimeIndicates when the grace period policy ends.datetimeApplicable only when the grace period policy exception is in place.
>>>> AmountPercentContains the penalty amount.object
AmountSpecifies the cancellation fee (if applicable) expressed as a fixed amount, if the guests cancels the booking.integerWhen a grace period policy exception is in place, the value will always be 100, that is, the guest is charged 100% when they cancel the booking after the grace period.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integerNot applicable for grace period policy exception.
CurrencyCodeSpecifies the currency used for pricing the penalty.enumerated stringThis is always the same for a property and is set by Booking.com.
Not applicable for grace period policy exception.

Include payments clarity package V2

Payments clarity package V2 (payment_clarity_package_v2) enables you to see payment and withheld tax related information.

View the following information in the response:

  • Price details: Contains information on taxes and charges applied on the reservation.
  • Current balance: Specifies the current balance on the VCC.
  • Card expiration date: Specifies the date the VCC expires in YYYY-MM-DD format. This is Booking.com standard. ExpiryDate follows the physical credit card standard. Both refer to the same expiration date, but one is more specific.
  • Card activation date: Specifies the date the VCC was activated in YYYY-MM-DD format. Applicable only for Payments by Booking reservations and when the payout type is virtual credit card.
  • Withheld tax details: [Only for reservations on a property that is located in a region where Booking.com is obligated to withhold and remit taxes on behalf of the property] Specifies the total amount that Booking.com has withheld as tax for the reservation. You can identify this information where the TaxDescription > Text contains: {{Tax_Name}} (Withheld tax)`
  • Currency code: Specifies the currency code of the virtual credit card.

Testing Payments clarity package V2 before implementing

Test this feature before implementation due to changes in pricing structure and based on the following two critical changes:

  1. The computed amount in the total field is calculated differently.
  2. The Inclusive/Exclusive values for the Type field uses a different logic. For a detailed comparison, see comparing VCC payment V2 with Payments Clarity Package v2.

For example, if you have been validating whether fees, taxes or charges are included in the price when recalculating the reservation prices, then you must revisit the price calculation. Doing this can avoid showing incorrect reservation prices.

For more information on how to test by passing the Features: payment_clarity_package_v2 header parameter in your request header, see Implementing Payments clarity package v2.

Overrides include_price_details and vcc_payment_v2 features

If you switch to the Payments Clarity Package V2(payment_clarity_package_v2) feature, your price and payment data will now come exclusively from this feature, replacing the older include_price_details and vcc_payment_v2 features.

In case you have the Provider XML setting: Dummy credit card on Last Minute No CC Reservations turned on, then the API returns dummy credit card details on last minute or same day, or domestic bookers.

Expand to know more. You can notice that the card details are not real by looking for the following:
  • The VCC details are the same.
  • The credit card holder's name is NOCCRESERVATION.
  • The ExpireDate is one year from the date of reservation.

For more information on how to activate the Dummy credit card on Last Minute No CC Reservations XML setting, contact the Connectivity Support team.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> PriceDetailsContains the guest and property-level price details for the reservation.objectAlso includes withheld tax details for reservations on a property that is located in a region where Booking.com is obligated to withhold and remit taxes on behalf of the property.
If you previously used the features: Payments Clarity Package (vcc_payment_v2) or the Include Price Details (include_price_details), the definitions and calculations for the total amount under guest and hotel are now changed.
>>> GuestViewContains the guest-level price details for the reservation.objectSpecifies whether the guest paid the amount for Payments by Booking reservations. For non-Payments by Booking reservations (agency bookings), it indicates whether the amount is included in the total amount the guest will pay to the property.
>>>> TaxesContains tax details.object
>>>>> TaxContains tax details.object
AmountSpecifies the tax amount.integer
ChargeFrequencySpecifies the charge frequency.enumerated integerFor a list of charge frequency code, see charge type codes.
CodeSpecifies the tax code.integerNote that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint. For a list of fee tax type codes, see Tax type codes.
CurrencyCodeSpecifies the currency used for pricing the room.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
TypeSpecifies whether the guest paid or needs to pay the amount depending on whether the reservation is a Payments by Booking or for non-Payments by Booking or (agency bookings) reservations.enumerated stringPossible values are:
- Inclusive: For Payments by Booking reservations, specifies that the guest paid the amount for the reservations.
For non-Payments by Booking reservations (agency bookings), indicates that the amount is included in the total amount the guest will pay to the property.
- Exclusive: For Payments by Booking reservations, specifies that the guest did not pay the amount.
For non-Payments by Booking reservations (agency bookings), indicates that the amount is excluded in the total amount the guest will pay to the property.
>>>>>> TaxDescriptionContains the tax description.objectFor properties where Booking.com is obligated to withhold taxes, the response includes an additional entry for every tax component that Booking.com has to withhold with the value {{Tax_Name}} (Withheld tax) in the description.
>>>>>>> TextSpecifies the tax description.string
>>>> TotalContains the total amount paid by the guest.object
AmountSpecifies the total amount owed by or collected from the guest.integerThe total amount is computed based on the Inclusive/Exclusive value for each tax amount breakup.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
>>> HotelViewContains the property-level price details for the reservation.objectSpecifies whether the amount is included in the payout to the property or the amount that the property needs to collect from the guest.
>>>> TaxesContains tax details.object
>>>>> TaxContains individual tax or fee details.object
AmountSpecifies the tax amount.integer
ChargeFrequencySpecifies the charge frequency.enumerated integerFor a list of charge frequency code, see charge type codes.
CodeSpecifies the tax code.integerNote that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint. For a list of fee tax type codes, see Tax type codes.
CurrencyCodeSpecifies the currency used for pricing the room.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
TypeSpecifies whether the amount is included in the payout to the property or the amount that the property needs to collect from the guest depending on whether the reservation is a Payments by Booking or a non-Payments by Booking reservations (agency bookings) reservation.enumerated stringPossible values are:
- Inclusive: Specifies that the amount is included in the payout to the property.
- Exclusive: Specifies that the amount is excluded from the payout to the property or excluded in the total amount that the property should collect from the guest depending on whether the reservation is a Payments by Booking or a non-Payments by Booking reservations (agency bookings) reservation.
>>>>>> TaxDescriptionContains the tax description.objectFor properties where Booking.com is obligated to withhold taxes, the response includes an additional entry for every tax component that Booking.com has to withhold with the value {{Tax_Name}} (Withheld tax) in the description.
>>>>>>> TextSpecifies the tax description.string
>>>> TotalContains the total amount owed to the property.objectThe total amount is computed based on the Inclusive/Exclusive value for each amount.
AmountSpecifies the total amount owed to the property.integer
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
ResGlobalInfoContains more details on the reservation.objectThis includes comments, reservation ID, and details of the individual who made the reservation.
> CommentsContains all the comments about the reservation provided at the time of booking.object
> GuaranteeContains the card details as a guarantee for the reservation.object
>> GuaranteesAcceptedobject
>>> GuaranteeAcceptedobject
>>>> PaymentCardobject
EffectiveDateSpecifies the date that the card can be charged from.datetimeThis attribute exists only for virtual credit cards.
CurrentBalanceSpecifies the current balance that is chargeable on the virtual credit card.integerThis attribute exists only for virtual credit cards.
DecimalPlacesSpecifies the position of the decimal point (from right to left) in the current balance value.integerFor example, Amount=10599 with DecimalPlaces="2" represents 105.99.
CurrencyCodeSpecifies the currency code (ISO 4217) of the virtual credit card's current balance.string
VCCExpirationDateSpecifies the expiration date of the virtual credit card.stringThis attribute exists only for virtual credit cards.
VCCActivationDateSpecifies the virtual credit card activation date.stringApplicable only for Payments by Booking reservations and when the payout type is virtual credit card.
To view this element, make sure to enable the feature: Payments Clarity Package V2 (payment_clarity_package_v2)
Note: To enable/disable this feature, contact Connectivity Support.

Summary of different combinations of Tax > Type values

This table explains how the Tax > Type values (Inclusive/Exclusive) affect payment behavior in different scenarios.

ScenarioGuest ViewProperty ViewPayments by Booking behaviourAgency Booking behaviour
1ExclusiveExclusive- Fees/tax was not collected during the book process.
- Fees/tax will not be paid out to the property.
- Fees/tax will be collected from guests by the property at the time of check-in.
-
2ExclusiveInclusive- Fees/tax was not collected from the guest during booking.
- Fees/tax cost will be borne by Booking and paid out to the property as a benefit.
-
3InclusiveExclusive- Fees/tax was collected from the guest during booking.
- Fees/tax is withheld and will be paid directly to the authorities and not to property.
-
4InclusiveInclusive- Fees/tax was collected from the guest during booking.
- Fees/tax will be paid out to property.
Fees/tax will be collected from guests by the property.
  • Booking.com remits taxes when the property has all taxes and fees defined in scenario 3 and uses Payments by Booking.com virtual credit card (VCC) payouts.
  • The partner remits taxes when the property has all taxes and fees defined in scenario 4 and uses Payments by Booking.com virtual credit card (VCC) payouts.
  • Split tax obligations and remittance occur when the property has taxes and fees defined in scenarios 3 and 4, respectively, and uses Payments by Booking.com virtual credit card (VCC) payouts.

Include virtual credit card information

Implement the latest version: Payments Clarity Package V2(payment_clarity_package_v2) to get a detailed breakdown of each booking’s total price, including tax details. It also breaks down the amount based on the guest and the property's perspectives. To compare the difference in data between the two features, see Payment clarity package features comparison.

If you have been using this feature, we recommend you to test and migrate to the Payments Clarity Package V2(payment_clarity_package_v2) feature. For more help with the migration, contact Connectivity Support.

When the feature: Payments Clarity Package (vcc_payment_v2) is enabled, you can view the following information in the response:

  • Price details: Contains information on specified taxes and charges.
  • Current balance: Specifies the current balance on the VCC.
  • Card expiration date: Specifies the date the VCC expires in YYYY-MM-DD format. This is Booking.com standard. ExpiryDate follows the physical credit card standard. Both refer to the same expiration date, but one is more specific.
  • Card activation date: Specifies the date the VCC was activated in YYYY-MM-DD format.

If the Provider XML setting: Dummy credit card on Last Minute No CC Reservations is turned on, then the API returns dummy credit card details on last minute or same day, or domestic bookers. You can notice that the card details are not real by looking for the following:

  • The VCC details are the same.
  • The credit card holder's name is NOCCRESERVATION.
  • The ExpireDate is one year from the date of reservation.

For more information on how to activate the Dummy credit card on Last Minute No CC Reservations XML setting, contact the Connectivity Support team.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> Totalobject
AmountBeforeTax/AmountAfterTaxSpecifies the amount before or after tax.integerDepending on whether the tax amount is excluded/included for the current room type, the API returns AmountBeforeTax or Amountaftertax.
CurrencyCodeSpecifies the currency used for pricing the commission.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
>>> TaxesContains tax details.object
AmountSpecifies the tax amount.integer
CurrencyCodeSpecifies the currency used for pricing the commission.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
>>>> TaxContains tax details.object
AmountSpecifies the tax amount.integer
ChargeFrequencySpecifies the charge frequency.enumerated integerFor a list of charge frequency code, see charge type codes.
CodeSpecifies the tax code.integerNote that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint. For a list of fee tax type codes, see Tax type codes.
CurrencyCodeSpecifies the currency used for pricing the commission.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
TypeSpecifies whether this extra charge is included in the total amount.enumerated stringPossible values are:
- Inclusive: The extra charge is included in the total amount.
- Exclusive: The extra charge is excluded from the total amount.
>>>> TaxDescriptionContains the tax description.object
>>>>> TextSpecifies the tax description.string
ResGlobalInfoContains more details on the reservation.objectThis includes comments, reservation ID, and details of the individual who made the reservation.
> CommentsContains all the comments about the reservation provided at the time of booking.object
> GuaranteeContains the card details as a guarantee for the reservation.object
>> GuaranteesAcceptedobject
>>> GuaranteeAcceptedobject
>>>> PaymentCardobject
EffectiveDateSpecifies the date that the card can be charged from.datetimeThis attribute exists only for virtual credit cards.
CurrentBalanceSpecifies the current balance that is chargeable on the virtual credit card.integerThis attribute exists only for virtual credit cards.
DecimalPlacesSpecifies the position of the decimal point (from right to left) in the current balance value.integerFor example, Amount=10599 with DecimalPlaces="2" represents 105.99.
CurrencyCodeSpecifies the currency code (ISO 4217) of the virtual credit card's current balance.string
VCCExpirationDateSpecifies the expiration date of the virtual credit card.stringThis attribute exists only for virtual credit cards.

Include price details

Implement the latest version: Payments Clarity Package V2(payment_clarity_package_v2) to get a detailed breakdown of each booking’s total price, including tax details. It also breaks down the amount based on the guest and the property's perspectives.

If you have been using this feature, we recommend you to test and migrate to the Payments Clarity Package V2(payment_clarity_package_v2) feature. For more help with the migration, contact Connectivity Support.

When the feature: Include price details (include_price_details) is enabled, the API includes the VAT and city taxes details in the response. Properties can configure the setup of taxes and charges in the Booking.com Extranet. They can specify how VAT and city tax are calculated and can set up to 5 extra charges.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> TotalContains the room price details.object
AmountBeforeTax/AmountAfterTaxSpecifies the amount before or after tax.integerDepending on whether the tax amount is excluded/included for the current room type, the API returns AmountBeforeTax or Amountaftertax.
CurrencyCodeSpecifies the currency used for pricing the room.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
>>> TaxesContains tax details.object
AmountSpecifies the tax amount.integer
CurrencyCodeSpecifies the currency used for pricing the room.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
>>>> TaxContains tax details.object
AmountSpecifies the tax amount.integer
ChargeFrequencySpecifies the charge frequency.enumerated integerFor a list of charge frequency code, see charge type codes.
CodeSpecifies the tax code.integerFor a list of fee tax type codes, see Tax type codes.
CurrencyCodeSpecifies the currency used for pricing the room.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
TypeSpecifies whether this extra charge is included in the total amount.enumerated stringPossible values are:
- Inclusive: The extra charge is included in the total amount.
- Exclusive: The extra charge is excluded from the total amount.
>>>>> TaxDescriptionContains the tax description.object
>>>>>> TextSpecifies the tax description.string

Payment clarity package features comparison

The following table compares the data returned by both the vcc_payment_v2 and payment_clarity_package_v2 features:

Payment solutionResponse elements ChangedWhen using the Payments Clarity Package
(vcc_payment_v2)
When using the Payments Clarity Package V2
payment_clarity_package_v2 feature
VCC Bookings
Property where Booking.com is obligated to withhold tax
GuestView > Tax > Type
Inclusive/Exclusive
Indicates whether the taxes/fees are included in the room price that Booking.com shows to guests.Indicates whether Booking.com collected the taxes/fees amount from the guest during the booking process.
GuestView > TotalIndicates the price amount that Booking.com shows to guests.Indicates the total amount that Booking.com collected from the guests.
HotelView > Tax > Type
Inclusive/Exclusive
Indicates whether the taxes/fees are included in the room price of the reservation as specified in the Extranet VAT/tax/charges page.Indicates whether the taxes/fees amount is included in the payout to the property.
HotelView > TotalIndicates the price amount of the reservation.Indicates the total payout amount to the property.
VCC balanceIndicates the amount that properties can charge on the VCC.- Bookings with withheld tax: The amount that properties can charge on the VCC. Note that this excludes the withheld tax that Booking.com has withheld and will remit on property's behalf.
- Bookings without withheld tax: The amount that properties can charge on the VCC.
Bank transfer bookings
Property where Booking.com is obligated to withhold tax
GuestView > Tax > Type
Inclusive / Exclusive
Indicates whether the taxes/fees are included in the room price that Booking.com shows to guests.Indicates whether Booking.com collected the taxes/fees amount from the guest during the booking process.
GuestView > TotalIndicates the price amount that Booking.com shows to guests.Indicates the total amount that Booking.com collected from the guests.
HotelView > Tax > Type
Inclusive/Exclusive
Indicates whether the taxes/fees are included in the room price of the reservation as specified in the Extranet VAT/tax/charges page.Indicates whether the taxes/fees amount is included in the payout to the property.
HotelView > TotalIndicates the price amount of the reservation.Indicates the total payout amount to the property.
Agency bookings^GuestView > Tax > Type
Inclusive/Exclusive
Indicates whether the taxes/fees are included in the room price that Booking.com shows to guests.Indicates whether the taxes/fees amount is included in the total amount the guest will pay to the property.
GuestView > TotalIndicates the price amount that Booking.com shows to guests.Indicates the total amount the guest will pay to the property.
HotelView > Tax > Type
Inclusive/Exclusive
Indicates whether the taxes/fees are included in the room price of the reservation as specified in the Extranet VAT/tax/charges page.Indicates if the taxes/fees amount is included in the total amount that the property should collect from the guest.
HotelView > TotalIndicates the price amount of the reservation.Indicates the total amount the property should collect from the guest.

^ - HotelView > Total amount is always the same as the GuestView > Total amount.
   - HotelView > Tax > Type Inclusive/Exclusive value is always the same as the GuestView > Tax > Type Inclusive/Exclusive value.

Get extra information: Rate rewrite

When you enable the feature: Get extra information for reservations (res_extra_info), the API adds the following information to the reservation messages.

ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>> TPA_ExtensionsContains additional reservation details for each booked room.object
>>> RateRewriteContains the parent rate plan information when there is a rate rewrite.object
FromCodeSpecifies the rate ID of the booked rate of the room when the booked rate is rewritten from a parent rate.integer
FromNameSpecifies the name of the booked rate of the room when the booked rate is rewritten from a parent rate.string
ToCodeSpecifies the parent rate plan ID.integer
>>>> BookingConditionContains more information on the property's policy.objectNote that we show the information in the preferred language of the property's primary point of contact. If you have implemented the Content API, then you can set the language under ContactInfos ... >... Language for the ContactProfileType as general via the OTA_HotelDescriptiveContentNotif endpoint.
>>>>> RateGeniusContains whether the roomrate applied to the booking is a specially discounted genius rate.object
ValueSpecifies whether the roomrate applied to the booking is a specially discounted genius rate.booleanA reservation with the value set to false can show a genius discounted price, only if a genius discount has been added at the room level. For more information on how to set room-level genius rate discounts, see the Opportunities tab in the Extranet.
RateIdsSpecifies the rate category ID as known at the moment of reservation.integerIf the room is booked with a rate that is rewritten from a parent rate, the API specifies the rate category ID of the parent rate.

Get extra information: Services details

In addition to the rate rewrite information, when you enable the feature: Get extra information for reservations (res_extra_info), the API adds service details.

ElementAttributeDescriptionTypeNotes
> ServicesContains information about the services.object
>> ServiceContains information about individual services and freebies for guests who are Genius members.object
ServiceRPHSpecifies the index that links guests (ResGuest') to rooms (RoomStay`).object
ServiceInventoryCodeSpecifies the unique ID of the add-on.enumerated stringOnly returns an ID from the list of IDs in the ServiceInventoryCode table.
ServicePricingTypeSpecifies the pricing type code.enumerated stringOnly returns an ID from the list of IDs in the ServicePricingType table.
IDSpecifies the ID that represents the freebies for guests who are Genius members.enumerated string
InclusiveSpecifies whether the extra charge is included in the total amount.boolean
>>> ServiceDetailsContains the service details.enumerated stringThe service details can include one of the following values based on the pricing type code:
- GuestCount (number of guests).
- Timespan (number of nights).
- Fees (price to be paid for the add-ons).
>>>> SpecialRequestsContains any special requests selected by the guest.object
>>>>> SpecialRequestContains individual special requestsobject
NameSpecifies the service code.enumerated stringFor a full list of all available service names, see Service names/codes.
>>>>>> TextSpecifies the service descriptionenumerated stringFor a full list of all the available service descriptions, see Service names.
>>>> GuestCountsContains the guest count information.object
>>>>> GuestCountobject
CountSpecifies the guest count.integer
>>>>> TimeSpanContains the number of stay nights.object
DurationSpecifies the number of stay nights.integer
>>>>> FeesContains the price that the guest has to pay for the add-ons.object
>>>>>> FeeContains the price that the guest has to pay for the individual add-on.object
AmountSpecifies the price to be paid for the add-on.integer

Get extra information: Guest details

In addition to the rate rewrite and service details information, when you enable the feature: Get extra information for reservations (res_extra_info), the API:

  • Specifies whether the booker is travelling on business, including company name & tax.
  • Highlights whether the guest is a member of Booking.com's loyalty program, Genius and if they qualify for any available freebies, such as a welcome drink or a late check-out.
ElementAttributeDescriptionTypeNotes
RoomStaysContains the room reservation details.object
> RoomStayContains the room reservation details for each booked room.object
>>TPA_ExtensionsContains additional reservation details for each booked room.object
>>> reservation_extra_infoobject
bookerobject
>>>>> affiliationsContains the details of any affiliations that the person who made the booking might have.object
>>>>>> affiliationContains the company name and VAT number provided by the booker.object
nameSpecifies the company nameobject
numberSpecifies the VAT number for the company which the booker is affiliated to.object
numbertypeSpecifies the type. For example, vat.object
typeSpecifies the affiliation type. For example, company.enumerated string
>>>> flagsContains additional details about the booking.object
>>>>> flagobject
nameenumerated stringCan contain one of the following values:
- booker_is_genius: Indicates Whether the Booker is a member of Booking.com's loyalty program called Genius.
- no_cc_reservation: Indicates that the reservation doesn't need a credit card guarantee.
- no_address_reservation: Indicates that the reservation doesn't need to enter their address for the reservation.
- smart_flex_replacement_reservation: Indicates that Booking.com will provide an alternate reservation to the host if the guest cancels the reservation
- smart_flex_reservation: Indicates that Booking.com will pay the cancellation charge if guests cancel the reservation.

Get extra information: Include deposit payments

In addition to the rate rewrite and all the above mentioned details, when you enable the feature: Get extra information for reservations (res_extra_info), the API also specifies any prepayment details, if applicable for the reservation.

ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains additional details on special requests.object
> DepositPaymentsContains information about the payment of the reservation. Booking.com can now take payments from the guest on behalf of the property. Specifies the payout type such as bank transfer or virtual credit card.object
>> GuaranteePaymentIf the reservation doesn't require a prepayment, the payment section is omitted. (only the tag is returned)object
GuaranteeTypeSpecifies the guarantee payment type.stringCurrently supports the value PrePay.
>>> DescriptionContains payout type information.object
>>>> TextSpecifies the payment and payment options such as bank transfer or virtual credit card.object
>>>> AmountPercentContains the prepayment amount.object
AmountSpecifies the amount Booking.com collected from the guest during the booking process, when the payment option is bank transfer. For reservations with a virtual credit card as payment option, the amount refers to the payout amount to the property.integer
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
CurrencySpecifies the currency used for the prepayment amount.enumerated stringThis is always the same for a property and is set by Booking.com.

Include reservation response token

When you enable the feature: OTA hotel reservation response token (ota_res_response_token), the API response includes a new HotelReservationID tag for every reservation that includes a token in OTA responses. The token identifies the message the provider is replying to, so that the Booking.com system can then acknowledge that a message has been received by the provider.

ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains more details on special requests.object
> HotelReservationIDsContains the reservations details.object
> HotelReservationIDContains individual reservation message details.objectWhen the OTA hotel reservation response token feature is enabled, the API returns an additional HotelReservationID element with an alphanumeric value in the ResID_Value, if the API detects changes to the reservation details since the last retrieval.
ResID_SourceOnly available when the OTA hotel reservation response token feature is enabled. Specifies the reservation source.stringTo create a custom ResID_Source value, you must enable the connection setting "Include ResID_Source information in HotelReservationID". For more information on how to enable this setting, contact the Booking.com Connectivity Support team.
ResID_TypeOnly available when the OTA hotel reservation response token feature is enabled. Specifies the Booking.com reservation type.integerCan contain the following values:
- 14: new reservation
- 18: reservation was modified since the last retrieval.
ResID_ValueSpecifies the Booking.com reservation ID.stringCan contain 2 entries if the API detects that a reservation was changed before the provider could acknowledge the booking. While acknowledging a changed reservation, you must provide both the ResID_Values.
ResID_DateSpecifies the reservation creation date and time value.datetime

Include reservation-level guest count

When you enable the feature: Include reservation-level guest count (childcount), the API returns the number of adults and children (with their ages) that the booker searched for when making the booking. This information is added to the reservation message.

Disable Include room-level guest count

Before enabling this feature, make sure to disable the feature: Include room-level guest count (guestcount_per_room). If both the features are enabled, the API shows only the room-level guest count.

ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains additional details on special requests.object
> GuestCountsContains the number of adults and children (with their ages) per room reservation.object
>> GuestCountContains the number of adults and ages of individual children included while searching for a reservation.integer
AgeQualifyingCodeSpecifies a code that represents the guest's age. Each code represents an age range.integerThe supported codes are:
10 - Adult
8 - Child
CountSpecifies the guest count.integer
AgeSpecifies the age of the child guests.integer

Include reservation-level commission

When you enable the feature: Include total commission (include_total_commission), the API returns the total commission amount for all rooms for all nights of a reservation.

By default, the API displays the commission amount per room stay under the RoomStay element. A single reservation can include multiple room stays. But by enabling this feature, you can get the total commission amount for all rooms for all nights of the reservation.

You can use this value to check the commission amount calculated, as some non-refundable reservations may be eligible for commission even if the reservation was modified or cancelled.

ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains additional details on special requests.object
> TotalCommissionsContains commission details for all rooms in a reservation.object
>> CommissionPayableAmountSpecifies the total commission for all rooms in a reservation.object
AmountSpecifies the total commission amount.integer
DecimalPlacesSpecifies the position of the decimal point (from right to left) in the total commission amount.integer
CurrencyCodeSpecifies the currency used for pricing the commission.enumerated stringThis is always the same for a property and is set by Booking.com.
>> CommentSpecifies a comment.object

Include payment charges

When you enable the feature: ReservationsAPI Payment Charges (res_payment_charges), the API includes the following details for reservations that are paid through the PayByBooking payment method.

ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains additional details on special requests.object
> Totalobject
AmountAfterTaxSpecifies the total including taxes.integer
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer
CurrencyCodeSpecifies the currency used for pricing the commission.enumerated stringThis is always the same for a property and is set by Booking.com.
>> TPA_ExtensionsContains additional reservation details for each booked room.object
>>> TPA_ExtensionContains additional reservation details for each booked room.object
>>>> PaymentChargeContains the payment charge details.object
Amountinteger
CurrencyCodeSpecifies the currency used for pricing the charge.enumerated stringThis is always the same for a property and is set by Booking.com.
DecimalPlacesSpecifies the number of decimal places to represent the minor unit of a particular currency.integer

Include dummy credit card details for bank transfer payout

Enable this feature only if the property's payout method is set to bank transfer (BT).

If you enable the feature: Include dummy CC details for bank transfer payout (res_dummy_cc_on_bt), the API returns dummy credit card details in reservation messages when guests pay through an alternate payment method.

You can notice that the card details are not real by looking for the following:

  • The VCC details are the same.
  • The credit card holder's name is NOCCRESERVATION.
  • The ExpireDate is one year from the date of reservation.
ElementAttributeDescriptionTypeNotes
ResGlobalInfoContains more details on the reservation.objectThis includes comments, reservation ID, and details of the individual who made the reservation.
>>>> PaymentCardContains payment information.object
CardCodeSpecifies dummy credit card issuer details.enumerated string
CardNumberSpecifies dummy credit card number.string
SeriesCodeSpecifies dummy credit card CVC code.string
ExpireDateSpecifies dummy credit card expiration date.datetime
>>>>>>>> CardHolderNameSpecifies NOCCRESERVATION as the credit card holder's name.objectApplicable only for reservations paid through an alternate payment method.

Include Value adds details

Enable the feature: Include bundle details (include_bundle_details) to receive value added service details in the reservations response.

ElementAttributeDescriptionTypeNotes
>>> ValueAddedServicesSpecifies the details for the value-added services.object
NameSpecifies a name for the value-add collection.string
>>>> ValueAddedServiceSpecifies details for each of the value-added services.object
ServiceIdSpecifies the Booking.com value-add service ID.enumerated integerFor a list of supported services, their IDs and corresponding names, see implementing the Value adds catalog API.
AmountSpecifies the value adds worth for display purposes.integerShows the benefit of the service/value add.
currencyCodeSpecifies the currency code of the specified amount.integerDefault: Uses property's currency code.
PercentageSpecifies the percentage discount.numberAny value greater than 0 and less than 100.
HourSpecifies the maximum check-in time when service ID is 3003.integer
MinuteSpecifies the maximum massage duration per adult per stay when service ID is 4003.integer

<TPA_Extensions>
 <ValueAddedServices Name="fancy package">
 <ValueAddedService ServiceId="2001" Amount="50" CurrencyCode="USD"/>
 <ValueAddedService ServiceId="1001" />
 </ValueAddedServices>
</TPA_Extensions>

Include Timestamp of last update

ElementAttributeDescriptionTypeNotes
OTA_HotelResModifyNotifRQContains the response data.object
>HotelResModifiesContains the modified/cancelled property reservations for each specified property.object
>>HotelResModifyContains individual property reservation details that were modified/cancelled.object
>>>LastModifyDateTimeobject

Service names

The following table lists all the services code names and their associated descriptions. Based on the code in the response, you can identify the available services supported by the property for a specific reservation.

Code NameDescription
GF_1Early check in
GF_2Free airport shuttle
GF_3Free drink upon arrival
Gf_4Free bike rental
GF_5Give Genius guests 2 extra hours to check out
GF_6Free breakfast
GF_7Free parking on availability
GF_8Free Wifi

Service type ID

The following table lists all the services and their associated IDs. Based on the ID(s) in the response, you can identify the services or add-ons supported by the property for a reservation.

Service Type IDService Name
1Late Check-out
2Early Check-in
3Late Check-in
4Champagne
5Wine
6Flowers
7Attraction
8Airport Shuttle
9Parking
10Massage
11Facial
12Body
13Christmas
14New Year
15Celebration Package
16Ski Pass

Available price modes

The following table lists all the price modes and their corresponding IDs. Based on the ID in the response, you can identify the price mode that was used to calculate the room price for a reservation.

IDPrice mode
0Not applicable
1Per stay
2Per person per stay
3Per night
4Per person per night
5Percentage
6Per person per night restricted

Addon types

The following table lists all the addons and their respective IDs.

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

→ To know more about how to acknowledge modified or cancelled reservation messages, see Acknowledging modified/cancelled reservations.
→ For troubleshooting information, see Troubleshooting and list of error codes.