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.

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: Details each unique reservation per individual property.
• Room stay details: Consolidates reservation details per room booking.
• Guest details: Contains guest details.
• Booker details: Contains booker details.

Reservation details

Booked room details

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

Guest details

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

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.

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.

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.

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.

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.

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.

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 the existing Payments Clarity Package with the new 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.

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.

Summary of different combinations of Tax > Type values

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

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

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.

Payment clarity package features comparison

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

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

• Specifies the property's policies.
• Specifies more details about the price, such as whether the roomrate applied to the booking is a specially discounted genius rate.
• Specifies service details.
• Specifies extra details about the guests.
• Specifies deposit payment details.

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.

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.

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.

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.

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.

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.

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.

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.

Include Value adds details

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

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

Include Timestamp of last update

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.

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.

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.

Addon types

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

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.