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