Change Log

# New Features For technical details, such as sample output for each feature, please view the [technical documentation](chttps://developers.booking.com/api/technical.html?). # Version V2.9 (release date: January 19, 2022) ## /hotels * Added **"sustainability"** information via **"hotels_info"** extras parameter that returns information regarding the sustainability classification method developed by Booking.com. The **"has_badge"** field returns information regarding whether the property is classed as sustainable. ``` GET /hotels?extras=hotel_info,sustainability ``` ``` { "result": [ { "hotel_id": 10004, "hotel_data": { "hotel_description": "This is the best hotel in the world.", "country": "nl", "district_id": 145, "max_rooms_in_reservation": "0", "name": "The Toren", ... "sustainability": { "has_badge": true } ... } ] } ``` ## /hotelFacilityTypes * Deprecated **"type"** field. ``` { "result": [ { "name": "Parking", "hotel_facility_type_id": 2, "translations": [ { "name": "Parking", "language": "en" } ], "type": "boolean", // <- deprecated "facility_type_id": 1 } ] } ``` ## /roomFacilityTypes * Deprecated **"type"** field (see above for sample) ## /blockAvailability * Added **"charge_price"** to output for all online payments ``` GET /blockAvailability ``` ``` "incremental_price": [{ "net_price": 49.45, "charge_price": 49.45, "tax_price": 49.45, "extra_charges_breakdown": { "net_price_other_currency": { "price": 8.05, "currency": "EUR" } ] ``` * Additional improvements made to cancellation timelines, ensuring consistency across different endpoints (ie:avRooms). * Information relating to cancellation fee/charges is now returned as** "cancellation fee = net price + VAT"** * Change in handling null values. Demand API will return empty fields for **"from"** and **"until"** fields instead of **"0000 and 9999 year"**: before **"until"**: **"9999-12-31 23:59:59"**, now it won’t be returned. ``` "cancellation_info": [ { "timezone": "CST", "currency": "USD", "until": "2022-01-15 17:59:59", "fee": 0.0, "from": "2022-01-02 17:00:00" }, { "from": "2022-01-15 18:00:00", "fee": 67.5, "currency": "USD", "timezone": "CST" } ] ``` * **"Conditional charges"** are now displayed in the charge breakdown section. To receive conditional charges, extra parameters **"extra_charges"** and **"show_conditional_charges"** should be used. Conditional charges are always **"excluded"** and have additional attribute in the output **"is_conditional**". ``` GET /blockAvailability?extras=extra_charges,show_conditional_charges ``` ``` { "name": "Cleaning fee", "currency": "USD", "excluded": true, "type": "SERVICECHARGE", "is_conditional": true, "charge_amount": 150.0, "amount": 150.0, "name_id": 3, "charge_price_mode": 1 }, ``` * Added **"payment_options"** item on a block level, which can be retrieved using the extras parameter. This shows payment options for each block. ``` "payment_options": { "pay_later": "true", "pay_now": "true" } ``` where | pay_at_property | pay_now | model | |---|---|---| | "true" | "false" | **agent or pay** at **property** | | "false" | "true" | **pay now** | | "true" | "true" | **hybrid** | | "false" | "false" | **not supported** | These are the current available payment options based on the reservation policy from the accommodation: **pay_at_property** : specifies that the reservation should be charged by the property **pay_now** : specifies that the payment will be made at the time of the reservation. **pay_later** : specifies that the reservation should be paid prior to check-in in the payment timing determined by the policy **hybrid**: Specifies that the reservation can be charged by the property (**pay at property**) or at the time of the reservation (**pay now**) * Additional information regarding **"pay_later_collection_date"** added, indicating that *Payment Timing* is available. This will provide details on the expected day in which the payment collection will happen for the reservations as per policy. ``` "room_id": 10000, "pay_later_collection_date": "2016-10-16 00:00:00 +0100", "extrabed_adult_count": [ 1 ] ``` * Deprecated the following objects: * **"rack_rate"** * **"is_flash_deal"** * **"is_secret_deal"** * **"public_price"** * **"is_smart_deal"** * **"is_last_minute_deal"** * **"last_minute_deal_percentage"** * **"is_china_pos_rate"** ## /hotelAvailability * Added **"sustainability"** information via **"hotels_details"** extras parameter that returns information regarding the sustainability classification method developed by Booking.com. The **"has_badge"** field returns information regarding whether the property is classed as sustainable. ``` GET /hotelAvailability?extras=hotel_details,sustainability ``` ``` { "result": [ { "hotel_id": 10004, "hotel_data": { "hotel_description": "This is the best hotel in the world.", "country": "nl", "district_id": 145, "max_rooms_in_reservation": "0", "name": "The Toren", ... "sustainability": { "has_badge": true } ... } ] } ``` * Added **"&filter=sustainable"** parameter to expose list of properties that have a sustainability badge. ``` GET /hotelAvailability?extras=hotel_details,sustainability&filter=sustainable ``` * Added **"payment_options"** information via the **"block_payment_options"** extras parameter. ``` "payment_options": { "pay_later": "true", "pay_now": "true" } ``` ## /processBooking * Added the parameter **"payment_method"** to specify which method to use for an online payment. * The possible values are * **"vcc"** specifies that the reservation should be paid online with a virtual credit card * **"wallet"** specifies that the reservation should be paid online with the Booking Wallet * **"cc_sca"**" specifies that the reservation will be paid online with credit card authenticated with Strong Customer Authentication (SCA) * **"payment_instructions"**": specifies that the reservation should be charged by the property rather than online. * **"v_c_company_for_auth_form=[company_name]_"** can now be used in combination with** “payment_method=vcc"**, **"payment_method=wallet"** or **"payment_method=cc_sca"**. ``` POST /processBooking ``` ``` { "options": [ "allow_past" ], "payment_method": "vcc", "cc_number": 4111111111111111, "cc_expiration_date": "2030-03-01", "cc_cardholder":"io", "cc_cvc":"737", "payment_timing": "pay_later" } ``` * Added **“payment_timing"** input parameter to use when executing an online payment with VCC (virtual credit cards). * Possible values are: * **“pay_now" **(default value) * **“pay_later" ** * The above replaces the parameter **“pay_now=1"** (used to specify that the reservation should be paid online with a virtual credit card) will be deprecated. * Added the following new parameters for API users using Voxel Invoice Collection: * parameters **“vc_company_for_auth_form"** (name of the company) * **“vc_company_vat_number_for_invoices"** (VAT number) * **“vc_invoice"** (a flag that specifies an invoice is needed for the reservation, useful for those API users that are integrating with Voxel to gather invoices for their reservations) ## /hotelSustainabilityPractices _(new endpoint) _ * Added a new endpoint that provides information regarding sustainability practice objects and translations. * Output includes: * **"category"** * **"name"** * **"id"** * **"translations"** ``` "result": [{ "category": "Waste", "id": 435, "name": "Single-use plastic miniature shampoo, conditioner, and body wash bottles not used", "translations": [{ "category": "Waste", "language": "en", "name": "Single-use plastic miniature shampoo, conditioner, and body wash bottles not used" }, { "category": "Afval", "language": "nl", "name": "Geen plastic shampoo-, conditioner- en douchegelflesjes voor eenmalig gebruik" } ] }] ``` ## /avRooms * Added **"payment_options"** information, giving details regarding current block payment options. ``` "payment_options": { "pay_later": "true", "pay_now": "true" } ``` * Added detailed cancellation timelines as "**cancellation_info**" structure: ``` "cancellation_info": [ { "fee": 0.00, "currency": "USD", "timezone": "", "until": "2022-01-16 17:59:59" }, { "fee": 65.00, "currency": "USD", "timezone": "", "from": "2022-01-16 18:00:00" } ], ``` # Version 2.8 (release date: July 28, 2021) ## /hotels * Information added about private/professional hosts to the **"hotel_important_information"** field. Returned as a string “Managed by a private host". This is a new regulation that came into effect on Jan 1st 2021. Sample: ``` "hotel_important_information": "This property will not accommodate hen, stag or similar parties. If you cause damage to the property during your stay, you could be asked to pay up to EUR 300 after check-out, according to this property's <a target='_blank' href=\"https://booking.com/content/damage- policy.html\">Damage Policy</a>. Managed by a private host " ``` * Added property **"vat_number"** and **"legal_name"** to **“fiscal_info”**. **_Note_**: This information may not always exist or have been provided by the property. This is a restricted feature, contact your account manager if you wish to enable it. Sample: ``` "fiscal_info": { "vat_number": "AB001234567", "legal_name": "A.C.M.E. Inc." } ``` * Added a flag which indicates if the property is a Genius property ( **“is_genius_property: true”** ) in **“extras=hotel_info”**. This is a restricted feature, consult with your account manager if you wish to enable it. Sample: ``` "preferred": true, "city": "Amsterdam", "is_genius_property": true ``` ## /blockAvailability * Changes were made to **"cancellation_info"** to improve the cancellation schedule. Example of previous structure: ``` "cancellation_info": [ { "currency": "USD", "timezone": "EST", "from": "2020-11-24 18:00:00", "fee": 0.0, "until": "2021-05-30 00:00:00" }, { "currency": "USD", "until": "2021-05-30 00:00:00", "fee": 235.3, "timezone": "EDT", "from": "2021-05-30 00:00:00" } ], "refundable_until": "2021-05-29 23:59:59 -0400", ``` The following changes were made: Removed the **"from"** field out of the first block in the example above, since this is always **"now"**. Removed the **"until"** field out of the last block in the example above, since this is always **"forever"**. Example of new structure: ``` "cancellation_info":[ { "currency": "USD", "fee": 0.0, "timezone": "EDT", "until": "2021-08-10 23:59:59" }, { "currency": "USD", "fee": 100.0, "timezone": "EDT", "from": "2021-08-10 00:00:00", "until": "2021-08-20 23:59:59" }, { "currency": "USD", "fee": 271.5, "from": "2021-08-21 00:00:00", "timezone": "EDT" } ], ``` ## /bookingdetails * Added **“external_reservation_ids”**. Sample: ``` "external_reservation_ids": [ "02060x76x6x98xx851" ], ``` ## /reviews * Added new flag **“text_meets_guidelines: true”** to ensure that any reviews that have not been approved are hidden. Sample: ``` "text_meets_guidelines": true, "cons": "", "average_score": 9.0, "pros": "Best location in Amsterdam on a quiet street overlooking one of the main canals, with exceptionally friendly hotel staff." ``` ## /avRooms * A conditional charge is an excluded charge that may be added depending on circumstances (for example: a cleaning fee in case pets stay in the room). A new output field has been added **“is_conditional = true/false”**. Sample: ``` "exc": [ { "is_conditional": "true", "charge_amount": 6, "mode": 5, "amount": 4.93, "id": 22 } ] ``` * Partner commission Added more accurate calculation. # Version 2.7 (release date: November 24, 2020) ## /hotels * Added a **“regions_ids”** parameter inside the **“hotel_data”** object. Sample: ``` "region_ids": [ 1010, 2776 ], ``` * Added a **“adult_age_restriction”** parameter inside **“hotel_data”** object, for when the property has set a minimum and/or maximum age for guests. Sample: ``` "adult_age_restriction": { "adult_age_min": 18, "adult_age_max": 80 }, ``` * Added **“additional_policies”** in **“hotel_data”** for children and extra bed policies. Sample: ``` "additional_policies": { "child_min_age": 12, "cots_and_extra_beds": [ { "to_age": 4, "from_age": 2, "price_mode": "per_stay", "price": 0, "rate_type": "existing_bed" } ], "children_allowed": "true" } ``` * The **“occupancy”** information added inside the **“room_info”** object. Sample: ``` "occupancy": { "allow_cribs_and_extra_beds": "false", "max_occupancy": 2, "max_adults": 2, "max_cribs": 2, "max_children": 2, "max_extra_beds": 1 }, ``` * Within **“room_info”**, the **“max_persons”** and **“children_policy”** output parameters have both been deprecated. * The **"work friendly"** flag has been added at both property and room levels. The **“is_work_friendly tag”** identifies the room and/or property as being suitable as a temporary office. Property level information is returned with **“extra=hotel_info”** input parameter and room level information is returned with **“extra=room_info”** input parameter. Sample: ``` "is_work_friendly": "true", ``` ## /blockAvailability * Added a **“prepayment_info”** parameter inside the **“block”** object for when the property has a prepayment schedule. Returned when **extras=prepayment_info** input parameter is used. Sample: ``` "prepayment_info": [ { "price": 138, "from": "2020-10-18 21:45:53" }, { "from": "2020-10-27 00:00:00", "price": 322 } ], ``` * Added **“max_adults”** inside the **“block”** object to indicate the maximum number of adults allowable for the block. ___Note___: while allocating guests to the room, make sure the constraint: ( number of children + number of adults ≤ **"max_occupancy"** ) must be met. In the following sample, this room allows a combination of *3 adults*, or *2 adults 1 child*, or *1 adult 2 children*. Sample: ``` "max_adults": 3, "max_occupancy": 3, "max_children_free_age": 17, "max_children_free": 2, ``` * Added new child blocks as output parameters. The only noticeable difference is with **“block_id”**, where the last section is non-zero. Sample: ``` "block_id": "6506324_275664888_3_1_6047313952768", ``` * Removed the **“bed_configurations”** parameter from the **“block”** object as the information returned is inaccurate. ## /bookingDetails * Added an input parameter namely **“last_change_day”** in YYYY-MM-DD format that must be within the last 180 days. When used, only changes effected on the provided date are returned. * Changed **“guest_city”** to **“booker_city”** as an output parameter. * Added **“guest_name”** that returns all names of guests in a booking (if available). * Added **“smoking_preference”** as an output parameter; can be 'undefined', 'smoking' or 'non-smoking'. * Added **“guest_comments”** that returns comments provided by guests when booking. If **_/processBooking_** is used to make a booking, this would be data provided in **“comments”**. * Added **“nr_guests”** that returns number of guests for each room of a booking. * Added **“guest_email”** that returns email of guest(s). * Added **“user_device”** with possible values of “Computer”, “Mobile”, “Tablet”, or “Unknown”. * Added **“extra_charges_breakdown”** that provides all extra charges relevant to a booking. Sample: ``` extra_charges_breakdown":{ "extra_charge":[ { "amount": 26.34, "charge_amount": 9, "charge_price_mode": 5, "currency": "EUR", "excluded": false, "name": "VAT", "name_id": 21 }, { "amount": 20.49, "charge_amount": 7, "charge_price_mode": 5, "currency": "EUR", "excluded": false, "name": "City tax", "name_id": 22 } ] ``` * Added **“mealplan”** that provides meal inclusion to a booking. Sample: ``` "mealplan": { "dinner": { "price_per_person_per_night": "4.29", "number_of_persons": 2, "included": true, "number_of_nights": 3 }, "lunch": { "price_per_person_per_night": "4.29", "number_of_persons": 2, "included": true, "number_of_nights": 3 }, "breakfast": { "included": true, "number_of_nights": 3, "price_per_person_per_night": "4.29", "number_of_persons": 2 } ``` * Added **“has_more”** flag to indicate that there are more results. Sample: ``` { meta: { ruid: "UmFuxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" has_more: 1 }, result: [ ``` ## /processBooking * Added the **“room1”** input to indicate the specific number of adults and children in each room. *room1=A,3* refers to 1 adult and 1 child of 3-year-old. **_Note_**: This conflicts with **“guest_quantities”** (in that these parameters cannot be used together). If child blocks are used then room (number) needs to be used. Otherwise **“guest_quantities”** can be used but child blocks cannot be specified. * Added validation when both **Online Payments** and **Payment Instructions** are used in the same call. If a partner uses both **“pay_now=1”** and **“vc_company_for_auth_form”** in the same call they will receive the error message. Sample: ``` "errors": [ { "code": 1009, "message": "Validation errors: Argument pay_now is exclusive with vc_company_for_auth_form, but vc_company_for_auth_form was defined.; Argument vc_company_for_auth_form is exclusive with pay_now, but pay_now was defined.", "ruid": "UmFuxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } ] ``` # Version 2.6 (release date: April 16, 2020) ## /hotels Added a **“children_policy”** parameter inside the **“room_data”** structure as an indicator if the property can accommodate children and stay in the same requested room without additional charges. Sample: ``` "children_policy": { "max_age": 4, "max_allowed": 1, "min_age": 2 } ``` **“max_allowed”** is equivalent to **“max_children_free”** parameter and **“max_age”** is equivalent to **“max_children_free_age”** parameter that can be found on **/blockAvailability** endpoint. ## /hotelAvailability * **“guest_country”** is now a required input parameter. * It is now possible to limit the results based on the property’s facility types by passing the **“hotel_facility_type_ids”** parameter in the request. The full list of the facility type ids can be found in **/hotelFacilityTypes** endpoint. * Added an output parameter **“platform”** inside **“deal_tagging”** structure on two availability endpoints: **/hotelAvailability** and **/blockAvailability**. The parameter can have two values: **“Web”** - the price is for mobile web users. **“App”** - the price is for mobile app users. ## /blockAvailability * **“guest_cc”** and **“guest_qty”** or **“room1”** are now required input parameters. * Added an output parameter **“platform”** inside **“deal_tagging”** structure on two availability endpoints: **/hotelAvailability** and **/blockAvailability**. The parameter can have two values: **“Web”** - the price is for mobile web users. **“App”** - the price is for mobile app users. ## /bookingDetails * Improved the structure on the loyalty information by adding following output parameters: **“loyalty_member_data”**, **“fulfillment_at_utc”**, **“currency”**, **“payout_after”**, **“amount”**, **“fulfillment”**, **“is_eligible”**, **“type”** inside the **“rewards”** structure. Possible values for **“type”** are `mile, point, cash, voucher_money, voucher_subscription` and `voucher_percentage`. Possible values for **“fulfillment”** are `partner` and `booking.com`. Sample: ``` "loyalty": { "rewards": [ { "fulfillment_at_utc": "2020-02-10 00:00:00 UTC", "currency": "KRW", "payout_after": 64, "amount": 119907, "fulfillment": "partner", "loyalty_member_data": [ { "field_value": "abc@gmail.com", "field_name": "Email" } ], "is_eligible": 1, "type": "mile" } ] }, ``` * In case of Payments by Booking.com, new output parameters were added: cancellation fee and payment information on the response. Each of them requires a partner setting to be set appropriately in order for those to show. Output parameters: **"cancellation_fee"** **"direct_payment_info"** * More detailed information about cancellation reason, namely about whether the cancellation was performed by the property or the guest, can be obtained by passing **“extras=status_details”**. ## /processBooking * New functionality is added to Payments Instruction incorporating seven new parameters for all users. Input parameters: **"vc_itemised_charge_breakfast"** **"vc_itemised_charge_food_beverage"** **"vc_itemised_charge_internet"** **"vc_itemised_charge_parking"** **"vc_itemised_charge_phone"** **"vc_itemised_charge_taxes"** **"vc_itemised_charge_total"** * Now Payments Instruction functionality is available for all users. Input parameters: **"vc_company_for_auth_form"** **"vc_phones_for_auth_form_pin"** Output parameter: **"auth_form_url"** * It is now possible to specify an email container to send the invoice to by adding this parameter **“vc_invoice_email”** in the request. * It is now possible to request an invoice from the property on the Payment Instructions authorisation form with specific requirements. Input parameters: **"vc_company_vat_number_for_invoices"** **"vc_invoice"** **"vc_invoice_email"** **"vc_invoice_to_guest"** * Fixed bug with **“pay_now”** parameter. **/processBooking** will enforce the transaction to be in the Pay Now model when the **“pay_now”** parameter is added. An error message: **_“The requester tried to prepay for a hotel, and the hotel does not accept prepayments.”_** will return in the response if the property does not in the Pay Now model. # Version 2.5 (release date: September 10, 2019) ## Tagging Deals in the API This feature enables an identifier in the output of availability endpoints. This identifier specifies the public price (the non-discounted rack rate), the discount percentage, and the name of the deal. Sample: ``` "deal_tagging": { "discount_percentage": 20, "deal_name": "Sales Campaigns", "public_price": 100.1 } ``` ## /hotels * It is now possible to filter out properties based on the property type by adding **“hotel_type_ids”** in the request. Use the numeric id codes returned by **/hotelTypes** endpoint in the **“hotel_type_ids”** input. * Added **“hotel_description_formatted”** in the **“extras”** input parameter to be able to include line breaks in the **‘hotel_description’** output field. * To support bed configuration mapping for multiple bedrooms, **"bed_configurations"** has been moved inside **"bedrooms"**, and **"configuration_id"** has been removed. ## /processBooking Starting in September 2019, the EU will impose new requirements for authenticating online payments as part of the second Payment Services Directive (PSD2). Six (6) additional input parameters are now added for Strong Card Authentication (SCA) processing: * *sca_authentication_response* * *sca_cavv* * *sca_directory_response* * *sca_trans_id* * *sca_eci* * *sca_version* This development is only relevant to properties with the Exclusive and Hybrid Payment by Booking payment methods. ## /bookingDetails * It is now possible to display total transaction value (TTV) as an output. This value will display in the same currency the partner set for invoicing. * Two (2) fields have been added in the output: **“guest_price_local”** **“guest_price_euro”** These fields identify the total cost incurred for the guest(s) in both the property's local currency and in Euros. # Version 2.4 (release date: February 21, 2019)  ## ## /bookingDetails - The output field **stay_probability** has been added when the account has this output field enabled. - The output **rres_id** (room reservation id) has been added to the **rooms** object. ## ## Reservation Modification Endpoints - It is now possible to modify a reservation when an account has these endpoints enabled: **/canChangeHotelReservation**, **/changeHotelReservation**, **/canChangeRoomReservation**, **/changeRoomReservation**, and **/changeBooking**. - These endpoints enable the modification of one or more of the following: check-in/check-out dates, guest name, number of guests, smoking preference, and (virtual) credit card. ## # Version 2.3 (release date: October 12, 2018) ## ## /avRooms - Output is now customisable through the parameters **min_length_of_stay** and **max_length_of_stay** and option **show_cheapest_block_only**. ## ## /blockAvailability and /hotelAvailability - Availability can be queried up to 500 days into the future. ## ## /hotels - Added **email** to `hotel_data`. ## # Version 2.2 (release date: July 17, 2018) ## ## /hotels - Added **license_number** as a separate field in `hotel_data`. - Added **auto_tags** to `hotel_photos` object and `room_photos` object. - The output field **bed_configurations** is now available when **room_info** is passed to the **extras** parameter. - It is now possible to retrieve key collection data by passing **key_collection_info** to the **extras** parameter. ## ## /hotelAvailability - The output field **cheapest_breakfast_rate** is now available when **add_cheapest_breakfast_rate** is passed to the **extras** parameter. ## ## /blockAvailability - Added **license_number** as a separate field to block level object. ## ## /bookingDetails - Added **price_local** output field. This represents the total reservation cost in the local currency of the property. - It is now possible to retrieve key collection data by passing **key_collection_info** to the **extras** parameter. ## ## /reviews - It is now possible to pull reviews in all available languages by passing **all** to the **language** parameter. ## # Version 2.1  (release date: _approximately_ November 2017) ## ## /blockAvailability - Added **lunch_included** and **dinner_included** to block-level object. - The output field **hotel_url** has been added. - The output field **mealplan_description** is now provided when **mealplans** is passed to the **extras** parameter. ## ## /hotelAvailability - It is now possible to filter for properties that can be booked without a credit card by using **option=no_cc_filter**. ## ## ## /bookingDetails - Added to output: - Returns a list of rooms booked for each reservation. - Returns a breakdown of reservation charges. ## ## /processBooking - Added the new parameter **guest_emails**, which accepts a comma-separated list of emails, similar to **guest_names**. ## ## /autocomplete - Two-character inputs are now supported. ## ## /hotels - Hotel themes can now be provided in the output. ## ## All endpoints - RUIDs are now provided in both JSON and XML responses/output. ## ## Multiple endpoints - Language configuration for es-ar: Argentinian Spanish (es-ar) has been added to the list of permissible languages in the API.