Retrieving reservations using B.XML
Use the B.XML reservations API endpoint to implement a reservations' retrieval system for a property. You can retrieve new, modified or cancelled reservations using a single endpoint.
Understanding reservation response
As a response, the endpoint returns the same schema but with updated information for new, modified or cancelled reservations. The following table outlines the difference in the response schema:
| Reservations status | Response |
|---|---|
| New | Returns reservations object with new reservation details. |
| Modified | Returns reservations object with updated reservation details. |
| Cancelled | Returns the same reservations object but with different child objects. |
| No pending reservations | Returns an empty reservations object. |
Retrieving reservations
POST
https://secure-supply-xml.booking.com/hotels/xml/reservationsUse this endpoint to retrieve new, modified or cancelled property reservations.
To ensure timely delivery of data, call POST reservations once per twenty seconds. We do not recommend higher frequencies because of added overhead to servers and operations. Multiple concurrent calls are likewise not recommended.
Request body parameters
The following table describes the elements you can add in the request body:
Use the parameters 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.
| Element | Description | Type | Required/Optional | Notes |
|---|---|---|---|---|
request | Root element. | object | required | |
id | Specify a reservation ID to retrieve a single reservation. | integer | optional | Specify a reservation ID that is queued for B.XML retrieval. 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. |
hotel_id or hotel_ids | Specify the unique property ID(s), separated by comma, to limit results to those hotels. You can specify, for example, 10 property IDs. | integer | optional | You can use hotel_id or hotel_ids interchangeably to specify multiple property IDs. Use only commas to separate individual property IDs. 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 a 404 status. |
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. | datetime | optional | Using 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. |
limit | Specify a maximum number of reservations to return. Specify a value >=10 and <= 200. | integer | optional | The API may return reservations less than the specified limit based on the available reservations. Specifying a low value here while retrieving reservations during peak season can lead to a growing backlog of unprocessed reservations. This filter can improve latency at the expense of throughput, therefore it adds a risk of a throughput bottleneck. |
Request body example
This section contains a request body example that retrieves reservations for the property with ID 8011855 and that were made since 2022-07-01. It limits the query to 10 results.
<request>
<hotel_id>8011855,8135188</hotel_id>
<last_change>2022-07-01</last_change>
<limit>10</limit>
</request>Response body example
<reservations>
<reservation>
<booked_at>2022-07-18T11:15:36+00:00</booked_at>
<commissionamount>49.44</commissionamount>
<currencycode>EUR</currencycode>
<customer>
<address></address>
<cc_cvc></cc_cvc>
<cc_expiration_date></cc_expiration_date>
<cc_name></cc_name>
<cc_number></cc_number>
<cc_type></cc_type>
<city></city>
<company></company>
<countrycode>nl</countrycode>
<dc_issue_number></dc_issue_number>
<dc_start_date></dc_start_date>
<email></email>
<first_name>Samuel</first_name>
<last_name>West</last_name>
<preferred_language>en-gb</preferred_language>
<remarks></remarks>
<telephone></telephone>
<zip></zip>
</customer>
<date>2022-07-18</date>
<hotel_id>8011855</hotel_id>
<hotel_name>HillTop Hotel</hotel_name>
<id>3181367489</id>
<modified_at>2022-07-18T11:15:38+00:00</modified_at>
<reservation_extra_info>
<flags>
<flag name="booker_is_genius" />
</flags>
</reservation_extra_info>
<room>
<arrival_date>2022-07-20</arrival_date>
<cancel_penalties>
<cancel_penalty from="2022-07-18T11:15:36+00:00"
policy_code="152">
<amount_percent amount="0"
currency_code="EUR" />
</cancel_penalty>
</cancel_penalties>
<commissionamount>24.72</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2022-07-22</departure_date>
<extra_info>This double room features a bathrobe, hot tub and game console.</extra_info>
<facilities>Bath, TV, Hot tub, Bathrobe, Free toiletries, DVD player, Fan, Private bathroom, Bath or shower, Carpeted, Laptop safe, Soundproofing, Bidet, Game console, Clothes rack, Toilet paper, Infinity pool, Bottle of water, Chocolate or cookies, Wine glasses, Game console – Wii U, Game console – PS4, Body soap, Shower cap, Feather pillow, Mobile hotspot device</facilities>
<guest_counts>
<guest_count count="2"
type="adult" />
</guest_counts>
<guest_name>Jackson G</guest_name>
<id>801185502</id>
<info>Breakfast is included in the room rate.Children and Extra Bed Policy: All children are welcome. There is no capacity for extra beds in the room. The maximum number of total guests in a room is 6. There is no capacity for cots in the room. Deposit Policy: No prepayment is needed. Cancellation Policy: The guest can cancel free of charge at any time. </info>
<max_children>0</max_children>
<meal_plan>Breakfast is included in the room rate.</meal_plan>
<name> Double Room</name>
<occupancy>4</occupancy>
<price date="2022-07-20"
genius_rate="no"
rate_id="25279855"
rewritten_from_id="0"
rewritten_from_name="">86</price>
<price date="2022-07-21"
genius_rate="no"
rate_id="25279855"
rewritten_from_id="0"
rewritten_from_name="">86</price>
<price_details>
<guest>
<extracomponent amount="16"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="26.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="5.10"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>211.10</total>
</guest>
<hotel>
<extracomponent amount="16"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="26.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="5.10"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>172</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>3759106792</roomreservation_id>
<smoking>0</smoking>
<totalprice>172</totalprice>
</room>
<room>
<arrival_date>2022-07-20</arrival_date>
<cancel_penalties>
<cancel_penalty from="2022-07-18T11:15:37+00:00"
policy_code="152">
<amount_percent amount="0"
currency_code="EUR" />
</cancel_penalty>
</cancel_penalties>
<commissionamount>24.72</commissionamount>
<currencycode>EUR</currencycode>
<departure_date>2022-07-22</departure_date>
<extra_info>This double room features a bathrobe, hot tub and game console.</extra_info>
<facilities>Bath, TV, Hot tub, Bathrobe, Free toiletries, DVD player, Fan, Private bathroom, Bath or shower, Carpeted, Laptop safe, Soundproofing, Bidet, Game console, Clothes rack, Toilet paper, Infinity pool, Bottle of water, Chocolate or cookies, Wine glasses, Game console – Wii U, Game console – PS4, Body soap, Shower cap, Feather pillow, Mobile hotspot device</facilities>
<guest_counts>
<guest_count count="2"
type="adult" />
</guest_counts>
<guest_name>Morgan Best</guest_name>
<id>801185502</id>
<info>Breakfast is included in the room rate.Children and Extra Bed Policy: All children are welcome. There is no capacity for extra beds in the room. The maximum number of total guests in a room is 6. There is no capacity for cots in the room. Deposit Policy: No prepayment is needed. Cancellation Policy: The guest can cancel free of charge at any time. </info>
<max_children>0</max_children>
<meal_plan>Breakfast is included in the room rate.</meal_plan>
<name> Double Room</name>
<occupancy>4</occupancy>
<price date="2022-07-20"
genius_rate="no"
rate_id="25279855"
rewritten_from_id="0"
rewritten_from_name="">86</price>
<price date="2022-07-21"
genius_rate="no"
rate_id="25279855"
rewritten_from_id="0"
rewritten_from_name="">86</price>
<price_details>
<guest>
<extracomponent amount="16"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="26.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="5.10"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>211.10</total>
</guest>
<hotel>
<extracomponent amount="16"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Bed linens fee" />
<extracomponent amount="18"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="no"
text="Gas fee" />
<extracomponent amount="26.24"
currency="EUR"
included="yes"
per_night="no"
per_person="no"
percentage="18%"
text="VAT" />
<extracomponent amount="5.10"
currency="EUR"
included="no"
per_night="no"
per_person="no"
percentage="3.5%"
text="City tax" />
<total>172</total>
</hotel>
</price_details>
<remarks></remarks>
<roomreservation_id>3759106815</roomreservation_id>
<smoking>0</smoking>
<totalprice>172</totalprice>
</room>
<status>new</status>
<time>13:15:36</time>
<totalprice>344</totalprice>
</reservation>
</reservations>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YQBqQix6ji/9NJZszNfyLEN341sSHgfn7oOvO1FXnOuIZUzD7QpzEjjgngxow5smUh6QycgeDycxUmzDH40OxEI=] -->Response body elements
Depending on the number of properties you handle and the number of reservations per each property, the API can return a long response body. 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
This table lists the response elements that consolidate details per reservation.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation | object | ||
>> booked_at | Contains the date and time the reservation was generated. | datetime | To view this element, make sure to enable the feature:Timestamp of last update for reservation (res_modify_timestamp). | |
>> commissionamount | Contains the commission information for each reservation that the property owes to Booking.com. | float | Empty if the reservation is cancelled. | |
>> currencycode | Specifies the currency used for the commission. | enumerated string | Follows the ISO 4217 currency code. This is always the same for a property and is set by Booking.com. |
Customer details
The following table lists all the details related to the booker. 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 <cc_name>NOCCRESERVATION</cc_name>.
Accessing credit card or virtual credit card details via the API
If you don’t receive the credit card or virtual credit card details in the reservation messages, maybe the property has opted in to not receiving them. You can manage your properties’ access to credit card or virtual credit card details on their behalf via the Provider Portal. To learn more, see the Provider Portal self-help guide.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> customer | Contains the booker details for the reservation. | object | ||
>> address | Contains the address details of the booker. | string | ||
>> cc_current_balance | Specifies the virtual credit card's current balance. | integer | 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. | |
>> cc_cvc | Specifies the credit card verification code as entered by the booker. | integer | ||
>> cc_expiration_date | Specifies the credit card expiration date as entered by the booker. | integer | ||
>> currencycode | Specifies the currency code of the virtual credit card. | enumerated string | Uses the ISO 4217 format. Takes the same currency as that of the virtual credit card's current balance, which was used when booking the reservation. Applicable only for Payments by Booking reservations and 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. | |
>> cc_name | Specifies the credit card holder's name. | string | If the API returns NOCCRESERVATION, then the reservation message contains dummy credit card details. | |
>> cc_number | Specifies the credit card number. | integer | ||
>> cc_type | Specifies the credit card type. | enumerated string | ||
>> city | Specifies the booker's residing city. | string | ||
>> company | Specifies the company where the booker works, or made the reservation for. | string | ||
>> countrycode | Specifies the booker's residing country as a country code (uses ISO 3166 format). | string | ||
>> dc_issue_number | [Only applicable for Maestro (Switch) debit cards] Specifies the Issue number. | integer | ||
>> dc_start_date | [Only applicable for Maestro (Switch) debit cards] Specifies the start date. | datetime | ||
>> email | Specifies the email address of the booker. | string | ||
>> first_name | Specifies the first name of the booker. | string | ||
>> last_name | Specifies the last name of the booker. | string | ||
>> preferred_language | Specifies the preferred langugage of the guest in the ISO language code format. | string | To view this element, make sure to enable the feature: Include Preferred language in Customer (res_customer_preferred_lang). Note: To enable/disable this feature, contact Connectivity Support. | |
>> remarks | Specifies any comments added by the booker regarding the reservation at the time of booking. | string | ||
>> telephone | Specifies the booker's telephone number. | string | ||
>> zip | Specifies the booker's postal code. | string | ||
> date | Specifies the reservation date. | datetime | ||
> hotel_id | Specifies the unique property ID as used by Booking.com where the reservation was made. | string | ||
> hotel_name | Specifies the property name as used by Booking.com where the reservation was made. | string | ||
> id | Specifies the reservation ID created by Booking.com for the reservation. | integer | ||
> modified_at | Specifies the date and time when the original reservation was modified. | object | To view this element, make sure to enable the feature:Timestamp of last update for reservation (res_modify_timestamp). | |
> reservation_extra_info | Specifies more information about the reservation. | object | To view this and its child elements, make sure to enable the feature: Get extra information for reservations (res_extra_info). |
Room details
The following table provides all the details related to the room.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>> arrival_date | Specifies the guest's arrival date. | datetime | ||
>> cancel_penalties | Contains the cancellation policy details. | object | To view this and its child elements, make sure to enable the feature: Add cancellation policy (res_cancel_policies). | |
>> commissionamount | Specifies the total commission amount due for this room for all nights combined. | float | The unit of currency is set by Booking.com under currencycode. | |
>> currencycode | Specifies the currency used for the prices in the reservation. | enumerated string | Follows the ISO 4217 currency code. This is always the same for a property and is set by Booking.com. | |
>> departure_date | Specifies the guest's departure date. | datetime | ||
>> extra_info | Specifies the extra room information as currently known for the booked room. | string | ||
>> facilities | Specifies the room facilities as displayed on the website at the time the reservation was made. | string | 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. | |
>> guest_counts | Contains the number of adults and children included while searching for a reservation. | object | To view this and its child elements, make sure to enable the feature: Include room-level guest count (guestcount_per_room). | |
>> guest_name | Specifies the guest name(s) for the room. | string | ||
>> id | Specifies the room type ID as used by Booking.com. | integer | ||
>> info | Specifies the room information as available on the website at the time of reservation. | string | 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. | |
>> max_children | Specifies the maximum number of children who can stay in the booked room for free. | string | This is a static setting defined per room. Guests cannot specify a value for the max_children 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 account managers or check in the Booking.com Extranet. | |
>> meal_plan | Specifies the mealplan (for example: breakfast, lunch or dinner) information that is applicable for the booked room. | string | 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. | |
>> name | Specifies the room name as available on the website. | string | Note that the room name might differ from the room name in the roomrates request, depending on the policy and/or rate type. Therefore, Booking.com recommends to map rooms based only on room ID and rate ID. 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. | |
>> occupancy | Contains the maximum occupancy for each room reservation. If the room has rate-level restrictions then this is the maximum occupancy for that rate. | integer | To see this element, make sure to enable the feature: Include room-level occupancy (include_room_level_occupancy). | |
>> numberofguests | Specifies the number of adult guests for this room as submitted by the guest on Booking.com. If the reservation uses a room rate that is not occupancy-based pricing, then it is the number of guests that the booker selected. | integer | If the feature: Include room-level guest count (guestcount_per_room). or Include room-level guest counts (old) (childcount_per_room) is enabled, then this information is hidden. | |
>> price | Specifies the price per night and rate category ID as known at the moment of reservation. | integer | To view all the attributes under the price element, make sure to enable the feature: Get extra information for reservations (res_extra_info). | |
date | Specifies the stay date for which the price is valid. | date | ||
genius_rate | Specifies whether the roomrate applied to the booking is a specially discounted genius rate. | boolean | A reservation with the genius_rate set to no 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 discount, see the Opportunities tab in the Extranet. | |
rate_id | Specifies the rate category ID as known at the moment of reservation. | integer | If the room is booked with a rate that is rewritten from a parent rate, the API specifies the rate ID of the parent rate. | |
rewritten_from_id | Specifies the rate ID of the booked rate of the room when the booked rate is rewritten from a parent rate. | integer | ||
rewritten_from_name | Specifies the name of the booked rate of the room when the booked rate is rewritten from a parent rate. | string | ||
>>> price_details | Specifies how VAT, city tax and extra charges are calculated. | object | For more information, see the Include price details (include_price_details), Payments Clarity Package (vcc_payment_v2) or Payments Clarity Package v2 (payment_clarity_package_v2) features. | |
>> remarks | string | |||
>> roomreservation_id | Specifies the room reservation ID as used by Booking.com to identify the booked room within the reservation. If a guest books multiple rooms, then a unique roomreservation_id is generated for each room. | integer | Empty if the reservation is cancelled. | |
>> smoking | Specifies whether smoking is allowed in the room. | boolean | Possible values are: - 0: Smoking is not allowed - 1: Smoking is allowed | |
>> total_price | Specifies the total price for the room for all nights combined. This shows the sum of all prices known at the time of reservation. | integer | Note that there may be some excluded charges from this price. The unit of currency is always the same for a property and is set by Booking.com. | |
>> addons | Contains any additional services added to the reservation. | object | ||
>>> addon | Contains individual additional service added to the reservation. | object | ||
>>>> name | Specifies the additional service's name. | string | For example, Breakfast. | |
>>>> nights | Specifies the number of nights the guest has booked for the service. | integer | ||
>>>> persons | Specifies the number of persons the addon is booked for. | integer | ||
>>>> price_mode | Specifies an integer identifying the price mode. | enumerated integer | For a full list of supported price modes, see Available price modes. | |
>>>> price_per_unit | Specifies the price per unit for this addon. | integer | ||
>>>> total_price | Specifies the total calculated price for this addon. | integer | ||
>>>> type | Specifies the addon type ID. | enumerated integer | For a full list of supported addons and their corresponding IDs, see Addon Types. |
Other details
The following table lists the rest of the reservation details.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> status | Specifies the reservation status. | enumerated string | Possible values are: - new - modified - cancelled | |
> time | Specifies the time at which the reservation was made in HH:MM:SS format. | time | ||
> total_cancellation_fee | [Only for cancelled reservations] Specifies the total amount of cancellation fees a guest has to pay because the cancellation was out of the cancellation policy. | integer | This value is computed as all cancelled rooms * all cancelled nights combined. | |
> total_price | Specifies the total amount of room sales for this reservation. | integer | This value is computed as all rooms * all nights combined. Note that there may be some excluded charges from this price. 0 if the reservation is cancelled. | |
>>> total | Specifies the total amount of extra charges that will be applied. Note that this price doesn't include excluded (included = "no") extra charges. | integer | ||
RUID | Specifies the unique request ID which is an encoded string. | object | You 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. |
Additional response elements
The following table describes the additional response elements:
Include room-level occupancy
Includes room-level adult count in XML reservations.
With this feature activated, you can see the number of adults booked for the roomrate.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>> occupancy | Contains the maximum occupancy for each room reservation. If the room has rate-level restrictions then this is the maximum occupancy for that rate. | integer |
Include reservation-level guest count
When you enable the feature: Include reservation-level guest count (childcount), the API includes the guest count at the reservation level and not under individual room level.
Disable room-level guest count
Before enabling this feature, make sure to disable the feature: Include room-level guest count. If both the features are enabled, the API shows only the room-level guest counts.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> reservation | Contains reservation details for each reservation | object | ||
> guest_counts | Contains the number of adults and children included while searching for a reservation. | object | ||
>> guest_count | Contains the number of adults and ages of individual children included while searching for a reservation. | integer | ||
count | Specifies the number of guests of a specified type and their age. | integer | ||
type | Specifies whether the guest falls under the following types, depending on their age: - adult - child | string | ||
age | If the guest type is child, then this specifies the age of the child. | integer |
Include room-level guest count
When you enable the feature: Include room-level guest count (guestcount_per_room), the API removes the <numberofguests> element in /hotels/xml/reservations and /hotels/xml/reservationssummary and replaces it with <guest_counts> in the response. Enabling this feature displays room-level guest counts.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
> guest_counts | Contains the number of adults and children included while searching for a reservation. | object | ||
>> guest_count | Contains the number of adults and ages of individual children included while searching for a reservation. | integer | ||
count | Specifies the number of guests of a specified type and their age. | integer | ||
type | Specifies whether the guest falls under the following types, depending on their age: - adult - child | string | ||
age | If the guest type is child, then this specifies the age of the child. | integer |
Include price details
When the Include price details (include_price_details) feature 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 configure up to 5 extra charges.
Changes to Include Price Details when upgrading to Payments Clarity Package v2
Before enabling this feature, consider implementing the feature: Payments Clarity Package v2 (
payment_clarity_package_v2). If both the features are enabled, the API shows only the changes for Payments Clarity Package v2 (payment_clarity_package_v2). | Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> price_details | Contains price details. | object | ||
>> guest | Contains the total amount paid by the guest and the details of the extra charges that were either included or excluded from the total amount. | object | ||
>>> extracomponent | Contains the details of the extra charges that were either included or excluded from the total amount paid by the guest. | object | ||
text | Specifies the description of the extra charge added by the property using the Booking.com Extranet. | string | ||
amount | Specifies the extra charge amount. | integer | ||
currency | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
included | Specifies whether this extra charge is included/excluded in the total amount. | boolean | Yes, denotes that the extra amount is included in the total amount. | |
per_night | Indicates whether this extra charge is applied per night. | boolean | ||
per_person | Indicates whether this extra charge is applied per person. | boolean | ||
percentage | The percentage of the extra charge applied to the total amount. | string | ||
>>> total | Specifies the total amount paid by the guest. | integer | ||
>> hotel | Contains the total amount owed to the property and the details of the extra charges that were either included or excluded from the total amount. | object | ||
>>> extracomponent | Contains the details of the extra charges that were either included or excluded from the total amount (that is owed to the property). | object | ||
text | Specifies the description of the extra charge added by the property using the Booking.com Extranet. | string | ||
amount | Specifies the extra charge amount. | integer | ||
currency | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
included | Specifies whether this extra charge is included/excluded in the total amount. | boolean | Yes, denotes that the extra amount is included in the total amount. | |
per_night | Indicates whether this extra charge is applied per night. | boolean | ||
per_person | Indicates whether this extra charge is applied per person | boolean | ||
percentage | The percentage of the extra charge applied to the total amount. | string | ||
>>> total | Specifies the total amount owed to the property. | integer |
Include payment charges
When you enable the feature: ReservationsAPI Payment Charges (res_payment_charges), for reservations that are paid through the PayByBooking method, you can get the payment charges in the response.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation | object | ||
>> paymentcharge | Contains the payment charges | integer |
Include virtual credit card details
When the Payments Clarity Package (vcc_payment_v2) feature is enabled, the API response includes the following child elements under reservation.customer.
cc_activation_datecc_current_balancecurrencycode: Specifies the currency code of the virtual credit card.vcc_expiration_date
The response also adds the price_details element under the reservation.room.
Upgrading Payments Clarity Package to Payments Clarity Package v2
Before implementing this feature, consider implementing the feature: Payments Clarity Package v2 (
payment_clarity_package_v2). If both the features are enabled, the API shows only the changes for Payments Clarity Package v2 (payment_clarity_package_v2). | Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation | object | ||
>> customer | Contains the booker details for the reservation. | object | ||
>>> cc_activation_date | Specifies the virtual credit card's activation date. | datetime | Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>>> cc_current_balance | Specifies the virtual credit card's current balance. | integer | Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>>> currencycode | Specifies the currency code of the virtual credit card. | enumerated string | Uses the ISO 4217 format. Takes the same currency as that of the virtual credit card's current balance, which was used when booking the reservation. Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>>> vcc_expiration_date | Specifies the virtual credit card's expiration date. | datetime | Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>>> price_details | object | |||
>>>> guest | Contains the total amount paid by the guest and the details of the extra charges that were either included or excluded from the total amount. | object | ||
>>>>> extracomponent | Contains the details of the extra charges that were either included or excluded from the total amount paid by the guest. | object | ||
text | Specifies the description of the extra charge as entered from the Booking.com Extranet by the property. | |||
amount | Specifies the extra charge amount. | integer | ||
currency | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
included | Specifies whether this extra charge is included in the total amount. | boolean | Yes, denotes that the extra amount is included in the total amount. | |
per_night | Indicates whether this extra charge is applied per night. | boolean | ||
per_person | Indicates whether this extra charge is applied per person | boolean | ||
percentage | The percentage of the extra charge applied to the total amount. | |||
>>>>> total | Specifies the total amount paid by the guest. | integer | ||
>>>> hotel | Contains the total amount owed to the property and the details of the extra charges that were either included or excluded from the total amount. | object | ||
>>>>> extracomponent | Contains the details of the extra charges that were either included or excluded from the total amount. | object | ||
text | Specifies the description of the extra charge as entered from the Booking.com Extranet by the property. | |||
amount | Specifies the extra charge amount. | integer | ||
currency | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
included | Specifies whether this extra charge is included in the total amount. | boolean | Yes, denotes that the extra amount is included in the total amount. | |
per_night | Indicates whether this extra charge is applied per night. | boolean | ||
per_person | Indicates whether this extra charge is applied per person | boolean | ||
percentage | The percentage of the extra charge applied to the total amount. | |||
>>>>> total | Specifies the total amount owed to the property. | integer |
Include Payments Clarity Package v2
Payments Clarity Package v2 (payment_clarity_package_v2) is a new and improved version of the Payments Clarity Package feature with significant changes to the response elements. It enables you to see payment and withheld tax related information.
When the feature: Payments Clarity Package v2 (payment_clarity_package_v2) is enabled, you can view the following information in the response:
cc_activation_date: Specifies the date the virtual credit card was activated in YYYY-MM-DD format.cc_current_balance: Specifies the current balance on the virtual credit card.currencycode: Specifies the currency code of the virtual credit card.vcc_expiration_date: Specifies the date the virtual credit card 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.- Price details: Contains information on specified taxes and charges. For Payments by Booking reservations, the total amount collected from the guest and the total payout amount to the property for the booked room are also specified.
- Withheld tax details: [Only for reservations of 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 under
extracomponent>textwith {{Tax_Name}} (Withheld tax).
Testing tax withholding component
For providers who manage properties located in a region where Booking.com is obligated to withhold and remit taxes on behalf of the property: Before testing this feature you need to fulfill certain additional requirements. For more information, contact the Connectivity Support.
Changes to Include Price Details and Payments Clarity Package behaviour
Before enabling this feature, note that the feature Payments Clarity Package v2 overrides the fields returned by the existing features Payments Clarity Package (vcc_payment_v2) and Include Price Details (include_price_details). If any of/both the existing features are enabled alongside with Payments Clarity Package v2, the API shows only the changes for Payments Clarity Package v2.
If you have been validating whether fees, taxes or charges are included in the price when recalculating the reservation prices with the Include Price Details (include_price_details) or the Payments Clarity Package (vcc_payment_v2) feature turned on, then you must revisit the price calculation as the relevant flags and amounts will change once the new Payments Clarity Package v2 (payment_clarity_package_v2) feature is enabled. Doing this can avoid showing incorrect reservation prices.
Note: To enable/disable this feature, contact Connectivity Support.
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 Connectivity Support.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation | object | ||
>> customer | Contains the booker details for the reservation. | object | ||
>>> cc_activation_date | Specifies the virtual credit card's activation date. | datetime | Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>>> cc_current_balance | Specifies the virtual credit card's current balance. | integer | - Bookings with withheld tax: The amount that properties can charge on the virtual credit card. 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. Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>>> currencycode | Specifies the currency code of the virtual credit card. | enumerated string | Uses the ISO 4217 format. Takes the same currency as that of the virtual credit card's current balance, which was used when booking the reservation. Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>>> vcc_expiration_date | Specifies the virtual credit card's expiration date. | datetime | Applicable only for Payments by Booking reservations and the payout type is virtual credit card. | |
>> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
> price_details | Contains price details. | object | 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. If you had implemented the feature Payments Clarity Package ( vcc_payment_v2), you can find an additional entry for every tax component that Booking.com has to withhold. | |
>> guest | Contains the total amount collected from the guest and the details of the extra charges that were either included or excluded from the collection for Payments by Booking reservations. For non-Payments by Booking reservations (agency bookings), contains the total amount that the guest will pay to the property for the booked room and the details of the extra charges that were either included or excluded from the amount the guest will pay to the property for the booked room. | object | ||
>>> extracomponent | object | |||
amount | Specifies the extra charge amount. | integer | ||
currency | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
included | Specifies whether this extra charge is included/excluded in the total amount. | boolean | Yes, denotes that the extra amount is included in the total amount. For different combinations of included value, see Summary of different combinations of included value. | |
per_night | Indicates whether this extra charge is applied per night. | boolean | ||
per_person | Indicates whether this extra charge is applied per person. | boolean | ||
percentage | The percentage of the extra charge applied to the total amount. | string | ||
text | Specifies the description of the extra charge as entered from the Booking.com Extranet by the property. | string | If you previously used the features: Payments Clarity Package (vcc_payment_v2) or the Include Price Details (include_price_details), for properties where Booking.com is obligated to withhold taxes, the response now includes an additional entry for every tax component that Booking.com has to withhold with the value {{Tax_Name}} (Withheld tax). | |
>>> total | Specifies the total amount collected from the guest for the booked room for Payments by Booking reservations. For non-Payments by Booking reservations (agency bookings), specifies the total amount that the guest will pay to the property for the booked room. | integer | The amount is computed based on the value in the included field. If you previously used the features: Payments Clarity Package ( vcc_payment_v2) or the Include Price Details (include_price_details), the definitions for the total amount is now changed. | |
>> hotel | Contains the total payment amount to the property and the details of the extra charges that were either included or excluded from that payout amount for Payments by Booking reservations for Payments by Booking reservations. For non-Payments by Booking reservations (agency bookings), contains the total amount that the property should collect from the guest and the details of the extra charges that were either included or excluded from that amount. | object | ||
>>> extracomponent | object | |||
amount | Specifies the extra charge amount. | integer | ||
currency | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
included | Specifies whether this extra charge is included/excluded in the total amount. | boolean | Yes, denotes that the extra amount is included in the total amount. For different combinations of included value, see Summary of different combinations of included value. | |
per_night | Indicates whether this extra charge is applied per night. | boolean | ||
per_person | Indicates whether this extra charge is applied per person | boolean | ||
percentage | The percentage of the extra charge applied to the total amount. | string | ||
text | Specifies the description of the extra charge as entered from the Booking.com Extranet by the property. | string | If you previously used the features: Payments Clarity Package (vcc_payment_v2) or the Include Price Details (include_price_details), for properties where Booking.com is obligated to withhold taxes, the response now includes an additional entry for every tax component that Booking.com has to withhold with the value {{Tax_Name}} (Withheld tax). | |
>>> total | Specifies the total payout amount to the property for the booked room for Payments by Booking reservations. For non-Payments by Booking reservations (agency bookings), specifies the total amount that the property should collect from the guest for the booked room. | integer | The amount is computed based on the value in the included field. If you previously used the features: Payments Clarity Package ( vcc_payment_v2) or the Include Price Details (include_price_details), the definitions for the total amount is now changed. |
Summary of different combinations of included value
The following table captures the intended behaviour of the included field. The value Excluded here denotes included="no"
| Scenario | Guest View | Property View | Payments by Booking behaviour | Agency Booking behaviour |
|---|---|---|---|---|
| 1 | Excluded | Excluded | - 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. | - |
| 2 | Excluded | Included | - 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. | - |
| 3 | Included | Excluded | - 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. | - |
| 4 | Included | Included | - 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.
To learn more about how to implement the feature, see Implementing Payment Clarity Package v2 using B.XML.
Include timestamp of last update
When you enable the feature: Timestamp of last update for reservation (res_modify_timestamp), the API displays the timestamp of:
- The original reservation, and,
- The modifications made to the existing reservation.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation. | object | ||
>> modified_at | Specifies the date and time when the original reservation was modified. | datetime | ||
>> booked_at | Specifies the date and time when the reservation was made. | datetime |
Include extra information
When you enable the feature: Get extra information for reservations (res_extra_info), the API adds the following information to the reservation messages.
- Specifies whether the booker is travelling on business, including company name & tax.
- Highlights the Genius status of the guest and if they qualify for any available freebies, such as a welcome drink or a late check-out.
- Specifies the payment options such as bank transfer or virtual credit card.
- Specifies more details about the price, such as whether the roomrate applied to the booking is a specially discounted genius rate.
The reservation can have two different currency codes
The first one is the property's default currency. It is the value in <currencycode>. The second one is the currency of the virtual credit card. This is applicable only when the payment_type is payment_on_Booking.com and the payout_type is Virtual credit card. The property can choose to receive the virtual credit card with a different currency instead of the default currency by using the Extranet.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation. | object | ||
>> reservation_extra_info | Specifies more information about the reservation. | object | ||
>>> booker | Specifies more information about the person who made the booking. | object | ||
>>>> affiliations | Specifies any affiliations that the person who made the booking might have. | object | ||
>>>>> affiliation | Specifies the company name and VAT number provided by the booker. | object | ||
name | Specifies the company name with which the booker is affiliated to. | string | ||
number | Specifies the VAT number for the company which the booker is affiliated to. | string | ||
numbertype | Specifies the type. For example, vat. | enumerated string | ||
type | Specifies the affiliation type. For example, company. | enumerated string | ||
>>> flags | Contains additional details about the booking. | object | ||
>>>> flag | object | |||
name | Specifies details such as whether the booker is a Genius customer, or more about the reservation. | enumerated string | Can 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. | |
>>> guests | object | |||
>>>> services | Contains the supported services for the staying guests. | object | ||
>>>>> service | Contains details of individual services supported by the property. | object | ||
name | Specifies the service name from a list of available services. | string | For a full list of available services, see Service Names. | |
>>>>>> text | Specifies the service description. | string | For a full list of available services, see Service Names. | |
>>> payer | Contains the reservation payment information. | object | ||
>>>> payments | Groups multiple reservation payment information. | object | ||
>>>>> payment | Specifies individual reservation payment information. | object | ||
amount | Specifies the amount Booking.com collected from the guest during the booking process, when the payout_type is BankTransfer. For reservations with Virtual credit card as payout_type, the amount refers to the payout amount to the property. | integer | ||
currency | Specifies the currency used for the payment. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. | |
payment_type | Specifies the payment type. | enumerated string | Can contain one of the following values: - payment_on_Booking.com | |
payout_type | Specifies the payout type. | enumerated string | Can contain one of the following values: - BankTransfer - Virtual credit card | |
>> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>>> price | Contains more details about the price. | number | ||
date | Specifies the stay date for which the price is valid. | date | ||
genius_rate | Specifies whether the roomrate applied to the booking is a specially discounted genius rate. | boolean | A reservation with the genius_rate set to no 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 discount, see the Opportunities tab in the Extranet. | |
rate_id | Specifies the rate category ID as known at the moment of reservation. | integer | If 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. | |
rewritten_from_id | Specifies the rate ID of the booked rate of the room when the booked rate is rewritten from a parent rate. | integer | ||
rewritten_from_name | Specifies the name of the booked rate of the room when the booked rate is rewritten from a parent rate. | string |
Include cancellation policy
When you enable the feature: Add_cancellation_policy (res_cancel_policies), The API returns the cancellation policy code which defines the cancellation policy in the response.
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.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation. | object | ||
>> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>>> cancel_penalties | Contains the cancellation policy details. | object | ||
>>>> cancel_penalty | Contains policy code, grace period before a penalty is applied (where applicable) and penalty amount details. | object | ||
policy_code | Specifies the policy code applied on the room rate. | string | If grace period policy exception applies, the API specifies another element with policy code grace_period and the deadline of the grace period. | |
>>>>> amount_percent | Contains the amount that the property should charge the guest as penalty, if the guest cancels before/after the deadline. | object | ||
amount | Specifies the penalty amount. | integer | When 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. | |
>>>>> deadline | Indicates when the grace period ends. | object | Applicable only when the grace period policy exception is in place. | |
time | Indicates when the grace period ends. | datetime | Applicable only when the grace period policy exception is in place. |
Include cancellation policy details
When you enable the feature: Add cancellation policy details (res_cancel_policy_details), the API returns the start and end of the cancellation policy period.
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 (res_cancel_policies) first when you implement Add cancellation policy details (res_cancel_policy_details).
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation. | object | ||
>> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>>> cancel_penalties | Contains the cancellation policy details. | object | ||
>>>> cancel_penalty | Contains policy code, grace period before a penalty is applied (where applicable) and penalty amount details. | object | ||
from | Specifies the start date when the policy is in effect. | datetime | Not applicable for grace period policy exception. | |
until | Specifies an end date until which the policy is in effect with the specified penalty amount. | datetime | Applicable only when the policy has an end date. Not applicable for grace period policy exception. | |
policy_code | Specifies the policy code applied on the room rate | string | If grace period policy exception applies, the API specifies another element with policy code grace_period and the deadline. | |
>>>>> amount_percent | Contains the amount that the property should charge the guest as penalty, if the guest cancels before/after the deadline. | object | Typically, if the from and until values are specified, it denotes a period before the deadline. | |
amount | Specifies the penalty amount. | integer | When 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. | |
currency_code | Specifies the currency code for the charge amount. | enumerated string | Follows the ISO 4217 currency code. The value is always the same for a property and is set by Booking.com. Not applicable for grace period policy exception. | |
>>>>> deadline | Indicates when the grace period policy exception ends. | object | Applicable only when the grace period policy exception is in place. | |
time | Indicates when the grace period policy ends. | datetime | Applicable only when the grace period policy exception is in place. |
Include promotion ID
When you enable the feature: Include promotion ID (include_promotion_id), the API response includes the promotion ID along with the reservation room price information.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservations | Root element. | object | ||
> reservation | Contains reservation details for each reservation. | object | ||
>> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>>> price | Contains more details about the price. | number | To view rate rewrite information, make sure to enable the feature: Get extra information for reservations (res_extra_info). | |
promotion_id | Specifies the promotion ID if the rate was calculated based on a promotion. | string |
Include room-level guest counts (old)
When you enable the feature: Include room-level guest counts (old) (childcount_per_room), the API returns the number of adults and children (with their ages) per room reservation.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
> room | Contains the booked room details including stay dates, guest information and room facilities. | object | ||
>> guest_counts | Contains the number of adults and children (with their ages) per room reservation. | object | ||
>>> guest_count | Contains the number of adults and ages of individual children included while searching for a reservation. | object | ||
count | Specifies the number of guests of a specified type and their age. | integer | ||
type | Specifies whether the guest falls under the following types, depending on their age: - adult - child | string | ||
age | If the guest type is child, then this specifies the age of the child. | integer |
Include dummy CC 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.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
reservation | Contains more details on the reservation. | object | This includes comments, reservation ID, and details of the individual who made the reservation. | |
> customer | Contains the booker details for the reservation. | object | ||
>> cc_type | Specifies dummy credit card issuer details. | enumerated string | ||
>> cc_number | Specifies dummy credit card number. | string | ||
>> cc_cvc | Specifies dummy credit card CVC code. | string | ||
>> cc_expiration_date | Specifies dummy credit card expiration date. | datetime | ||
>>> cc_name | Specifies NOCCRESERVATION as the credit card holder's name. | object | Applicable only for reservations paid through an alternate payment method. |
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 Name | Description |
|---|---|
| GF_1 | Early check in |
| GF_2 | Free airport shuttle |
| GF_3 | Free drink upon arrival |
| Gf_4 | Free bike rental |
| GF_5 | Give Genius guests 2 extra hours to check out |
| GF_6 | Free breakfast |
| GF_7 | Free parking on availability |
| GF_8 | Free Wifi |
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 ID | Service Name |
|---|---|
| 1 | Late Check-out |
| 2 | Early Check-in |
| 3 | Late Check-in |
| 4 | Champagne |
| 5 | Wine |
| 6 | Flowers |
| 7 | Attraction |
| 8 | Airport Shuttle |
| 9 | Parking |
| 10 | Massage |
| 11 | Facial |
| 12 | Body |
| 13 | Christmas |
| 14 | New Year |
| 15 | Celebration Package |
| 16 | Ski 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.
| ID | Price mode |
|---|---|
| 0 | Not applicable |
| 1 | Per stay |
| 2 | Per person per stay |
| 3 | Per night |
| 4 | Per person per night |
| 5 | Percentage |
| 6 | Per person per night restricted |
Addon types
The following table lists all the addons and their respective IDs.
| ID | Name |
|---|---|
| 1 | Breakfast |
| 2 | Continental breakfast |
| 3 | American breakfast |
| 4 | Buffet breakfast |
| 5 | Full english breakfast |
| 6 | Lunch |
| 7 | Dinner |
| 8 | Half board |
| 9 | Full board |
| 11 | Breakfast for Children |
| 12 | Continental breakfast for Children |
| 13 | American breakfast for Children |
| 14 | Buffet breakfast for Children |
| 15 | Full english breakfast for Children |
| 16 | Lunch for Children |
| 17 | Dinner for Children |
| 18 | Half board for Children |
| 19 | Full board for Children |
| 20 | WiFi |
| 21 | Internet |
| 22 | Parking space |
| 23 | Extrabed |
| 24 | Babycot |
Include Value adds details
Enable the feature: Include bundle details (include_bundle_details) to receive value adds details in the reservations response.
| Element | Attribute | Description | Type | Notes |
|---|---|---|---|---|
>>> value_added_services | Specifies the details for the value-added services. | object | ||
name | Specifies a name for the value-add collection. | string | ||
| >>>> value_added_service` | Specifies details for each of the value-added services. | object | ||
service_id | Specifies the Booking.com value-add service ID. | enumerated integer | For a list of supported services, their IDs and corresponding names, see Supported value-added services. | |
amount | Specifies the value adds worth for display purposes. | integer | Shows the benefit of the service/value add. | |
currency_code | Specifies the currency code of the specified amount. | integer | Default: Uses property's currency code. | |
percentage | Specifies the percentage discount. | number | Any value greater than 0 and less than 100. | |
hour | Specifies the maximum check-in time when service ID is 3003. | integer | ||
minute | Specifies the maximum massage duration per adult per stay when service ID is 4003. | integer |
<value_added_services name="fancy package">
<value_added_service service_id="2001" amount="50" currency_code="USD"/>
<value_added_service service_id="1001" />
</value_added_services>Quick Actions
→ For troubleshooting information, see Troubleshooting and list of error codes.