# Changelog archive **Find here a comprehensive history of all updates, improvements, and bug fixes across versions.** # 2024 Changelogs ## December 2024 This month we focused on order improvements in Demand API V3.1! Some of the key highlights include: ### Orders/preview **| New field | chargeable online price | orders/preview | Available to all partners |** > **We have introduced `chargeable online price` object in [orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) endpoint response:** * This object specifies the amount that will be charged online by Booking.com. * This amount will always be less than or equal to the total price. Note: This applies only if Booking.com is managing partner payments. For full details, refer to the [Accommodation pricing](/demand/docs/accommodations/prices-accommodations) section. Example: ```json { "chargeable_online": { "accommodation_currency": 121.03, "booker_currency": 121.03 } } ``` > * You can find this field in two places: * Order level: Located at accommodation.price.chargeable_online. * Product level: Located at accommodation.products[i].price.chargeable_online. The chargeable_online field is linked to the existing boolean flags: - accommodation.price.extra_charges.non_conditional[i].chargeable_online. - accommodation.products[i].price.extra_charges.non_conditional[i].chargeable_online. These flags indicate which charges contribute to the total chargeable amount represented by the chargeable_online field. Example with both boolean and price object: ```json { "price": { "base": { "accommodation_currency": 110.03, "booker_currency": 110.03 }, "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 21, "chargeable_online": true, "mode": "percentage", "percentage": 10.00, "total_amount": { "accommodation_currency": 11.00, "booker_currency": 11.00 }, "unit_amount": { "accommodation_currency": null, "booker_currency": null } } ] }, "chargeable_online": { "accommodation_currency": 121.03, "booker_currency": 121.03 }, "total": { "accommodation_currency": 125.53, "booker_currency": 125.53 } }, "room": 438312701 } ``` Important If you use `pay_at_the_property` payment timing, please disregard any `chargeable_online` field present in the response, as charges are handled directly by the property and not by Booking.com. ### Orders/create **| New error messages | payment failures | orders/create | Available to all partners |** > - When making a reservation using [Payments](/demand/docs/payments/overview) through the [orders/create](/demand/docs/open-api/demand-api/orders/orders/create) endpoint, and the payment fails, the response no longer returns the generic error `payment_refused` ( message: *Payment collection failed*). - Instead, if available, a more specific error message is provided, offering greater clarity about the cause of the failure. For a complete list of error codes and descriptions, please refer to the [payment error handling](//demand/docs/support/error-handling/payment-errors) section. ### Orders/details **| Flights orders inclusion | order/details | Available to all partners |** > **You can now check the flight details of an order via the [order/details](/demand/docs/open-api/demand-api/orders/orders/details) endpoint.** You just need to pass "flights" as service when calling this endpoint: ```json { "created": { "from": "2024-09-25T00:00:00+00:00", "to": "2024-09-30T23:00:00+00:00" }, "services": [ "flights" ], "sort": { "by": "created", "direction": "ascending" }, "maximum_results": 100, "currency": "EUR" } ``` Refer to the [orders/details guide](/demand/docs/orders-api/order-details#/orders/details/) for more details and examples. ### Orders/details/accommodations **| New fields | /orders/details/accommodations | all partners if enabled |** > **We have introduced the `External account id` field under the `booker` object, in this endpoint response**: * This is a unique identifier that represents the account provided by the partner in Booking.com settings. * This field is used to link a specific accommodation order to the corresponding external account. This field is not displayed if partner does not have a PII agreement or has not enabled the setting. Example: ```json { "booker": { "external_account": 13610217, "platform": "mobile" } } ``` Refer to the [Order/details guide](https://developers.booking.com/demand/docs/orders-api/order-details#external-account-id) for more details. ### Order/details/cars and flights **| New endpoints | order/details/car | order/details/flights | Available to all partners |** > **You can use now check details of cars or flight orders, via these new endpoints. They follow a similar pattern to that used for accommodations.**: Refer to the [order/details/cars](/demand/docs/orders-api/order-details#/orders/details/cars) and [order/details/flights](/demand/docs/orders-api/order-details#/orders/details/flights) guidelines for examples and best practices. ### Other improvements In addition to all these new features, we have made general improvements to the rate calculation, aiming to [reduce discrepancies between the pricing](/demand/docs/accommodations/prices-accommodations#price-variations) returned in the [orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) endpoint and that in the [accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) endpoint. ## November 2024 | Demand API V3.1 | New fields: deals, chargeable online | Minessota regulation | Orders | ### Orders #### [orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) We have introduced new fields in the endpoint response: * `deal`: It returns the breakdown of the deal applicable to the product, the percentage of the discount, price before discounts and deal tag for better identification (genius, black_friday, seasonal_deal, etc.) Refer to the [Deals section](/demand/docs/accommodations/discounts/) for more details and examples. Example: ```json { "deal": { "discount_percentage": 15, "public_price": 1069.93, "tags": [ "genius" ] } } ``` * `chargeable_online`: This field identifies whether a particular extra charge contributes to the chargeable amount handled by Booking.com. * You can find it under `extra_charges.non_conditional` field in two places: the accommodation price summary and the product list price. Note: This is only applicable if Booking.com is managing partner payments. Refer to the [Accommodation pricing](/demand/docs/accommodations/prices-accommodations) section for all the details. Example: ```json { "price": { "base": { "accommodation_currency": 110.03, "booker_currency": 110.03 }, "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 21, "chargeable_online": true, "mode": "percentage", "percentage": 10.00, "total_amount": { "accommodation_currency": 11.00, "booker_currency": 11.00 }, "unit_amount": { "accommodation_currency": null, "booker_currency": null } } ] }, "chargeable_online": { "accommodation_currency": 121.03, "booker_currency": 121.03 }, "total": { "accommodation_currency": 125.53, "booker_currency": 125.53 } }, "room": 438312701 } ``` Important If you use `pay_at_the_property` payment timing, please disregard any `chargeable_online` fields present in the response, as any charges are handled by the property and not by Booking.com. #### [/orders/details/accommodations](/demand/docs/open-api/demand-api/orders/orders/details/accommodations) We have introduced new fields to this endpoint response: > * `Credit_slip`: * It identifies the number of the financial document issued by Booking.com to partners detailing the payout amount and the associated transaction information. * This way partners can track commission payments and identify in which transfer they were paid. * `Stay_probability_score`: * Score that predicts the likelihood of a traveller's intent to stay, based on internal calculations. * A score of 0 indicates the highest likelihood of cancellation, while a score of 1 represents the highest likelihood of the traveller staying. Note: This score may not always be available. Example: ```json { "booker": { "platform": "mobile" }, "cancellation_details": { ... }, "credit_slip": 1223445, "currency": { "accommodation": "EUR", "booker": "USD" }, "total": { "accommodation_currency": 170.01, "booker_currency": 186.87 }, "products": [ { ... "price": { ... }, "total": { "accommodation_currency": 200.97, "booker_currency": 220.9 } } ], "reservation": 12345678, "status": "booked", "stay_probability": 0.12 } ``` ### Accommodation Demand API v3 and v2, Minnesota state new legislation. This legislation has now been superseded by the [FTC's national Rule on Unfair or Deceptive Fees](/demand/docs/compliance/ftc-compliance), which came into effect across the USA on 12th May 2025. > **We have adapted accommodation endpoints to new price transparency law for Minnesota state**. Our Demand API now displays prices in full (including all mandatory fees) for both properties located in Minnesota and travellers searching for accommodation from this state. | Demand API version | Endpoints | Action | | --- | --- | --- | | **v3** | [/accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search)[/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability)[/accommodations/bulk-availability](/demand/docs/open-api/demand-api/accommodations/accommodations/bulk-availability) | In the `booker.state` field, specify the "**mn**" state (for Minnesota). | | **v2** | /blockAvailability /hotelAvailabilityPass | Pass the “**guest_region=mn**” parameter in the request. | | | /processBooking | Add an additional body parameter "**booker_region": "mn**" to ensure that the price displayed during the search matches the price processed during booking. | Important If you are unable to provide state information as an input, you can pass the "mn" parameter for all US reservations as follows: - `guest_region` in version 2. - `region` in version 3. This ensures that the room rate + charge (excluding tax) is returned, allowing the price displayed during search to match the price processed at booking. ### Cars Demand API v3.1, city id, Available to pilot partners. * The new field `city id` has been included in: * The API response for [/cars/depots](/demand/docs/open-api/demand-api/cars/depots) under the "location" section: * The city id points to the city where the depot is located. Example: ```json { "location": { "address": "5 Aankomstpassage", "airport": "AMS", "city": -2140479, "coordinates": { "latitude": 52.309456, "longitude": 4.762266 }, "country": "nl", "name": { "en-gb": "Amsterdam Airport Schiphol - Terminal 3", "nl": "Amsterdam Luchthaven Schiphol - Terminal 3" }, "post_code": "1118 AX" } } ``` > * In [/search](/demand/docs/open-api/demand-api/cars/search) endpoint request so you can now search for car rental services in a specific city too, by adding the city id in the location field. Example: ```json { "route": { "dropoff": { "datetime": "2024-11-10T11:05:00", "location": { "city": -393418 } }, "pickup": { "datetime": "2024-11-08T11:05:00", "location": { "city": -393418 } } } } ``` This field follows the Demand API standard format so is compatible with [common/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities) ids endpoint. ## October 2024 | Demand API V3.1 | New features | Damage policy | Pay at the property: Prepayment timeline + CVC required | ### accommodations/details endpoint **| New feature | Damage policy | Available to all partners |** > We have introduced a damage policy in the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint. The `damage` field is now included under `policies` and contains: * The amount collected in case of damage (set by the property) and its currency. * Information regarding the deposit, which includes: * Dates for deposit collection (between 7 and 14 days before checkin date) and refund (between 7 and 14 days after checkout). * The [Payment method](/demand/docs/payments/payments-methods) for the collection/refund. Example: ```json { "damage": { "amount": 50.00, "currency": "EUR", "deposit": { "collect": { "date": { "days_offset": 0, "reference_date": "checkin" }, "payment_method": "credit_card" }, "refund": { "date": { "days_offset": 0, "reference_date": "checkout" }, "payment_method": "credit_card" } } } } ``` * If `deposit` is null, then no deposit is collected before checkin. However, the specified amount will be charged in case of damage. * If the `deposit` is not null, the stated deposit amount would be collected on the specified date using the designated payment method. **| New payment fields | CVC required | Only for Pay at the property |** > * We have added two new fields to the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint: `cvc_required` and `amex_cvc_required` under the `payment` object. * These fields indicate whether the card cvc number is required for the order and, expecifically for American Express cards, whether the amex_cvc number is required. Examples: ```json { "payment": { "amex_cvc_required": false, "cvc_required": true, "methods": { "cards": [ 1, 2, 3, 5, 7, 10 ], "cash": false, "virtual_cards": [ 1, 2, 3 ] }, "timings": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } } ``` And for American Express payments, when amex_cvc number is required: ```json { "payment": { "amex_cvc_required": true, "cvc_required": true, "methods": { "cards": [ 1, 2, 3 ], "cash": true, "virtual_cards": [ 1, 2, 3 ] }, "timings": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } } ``` ### orders/preview endpoint **| New Feature | Pay at the property - Prepayment timeline | Available to all partners |** > We have added support for prepayment in pay at the property timelines in [/orders/preview endpoint](/demand/docs/open-api/demand-api/orders/orders/preview). * Under general_policies->payment-> pay_at_the_property, we now show the prepayment timeline for properties. * This way properties can decide whether to collect payments before checkin. For examples and details refer to [Payment timings](/demand/docs/payments/payments-timings) section. ### Bug fixes | Bug and endpoint | Description | | --- | --- | | | allInclusive not supported | [order/preview](/demand/docs/open-api/demand-api/orders/orders/preview) | | Now we support *allInclusive* mealPlan policy for [Third- party inventory](/demand/docs/accommodations/tpi/about-tpi) products in order/preview. | | | 404 error code with empty response | [orders/create](/demand/docs/open-api/demand-api/orders/orders/create) | | If a unauthorised partner calls orders/create, it returned an empty response together with code 404 (“internal server error” message), which is not correct. Unauthorised calls to orders/create are getting now the correct error code and message: [“not found” (404)](//demand/docs/support/error-handling/http-4xx-scenarios#404---not-found). | ## September 2024 | Demand API V3 all versions | New filter | Trader information | Number of rooms | IP Address for riskified | ### /accommodations/details/changes endpoint > **We have included the filterBy countries or cities options for [/accommodations/details/changes](/demand/docs/open-api/demand-api/accommodations/accommodations/details/changes) endpoint.** * When using any of these filters in your [/accommodations/details/changes](/demand/docs/open-api/demand-api/accommodations/accommodations/details/changes) request, the response will narrow down based on those. * This way you can retrieve the list of accommodations that have been modified in the last 24h in those countries or cities of your interest. Note that a list of max 100 countries or cities is supported. Example with countries: ```json { "last_change": "2024-09-29T17:00:00+00:00", "filters": { "countries": [ "nl", "es", "in" ] } } ``` ### /accommodations/details endpoint | Demand API 3.1 | New feature | Trader information | /accommodations/details | > **We have added a new object named `trader` to be compliant with the Digital Services Act (“DSA”)** * The trader information can be obtained when calling the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint, under the `description` field. * It provides data about: address, email, name, registration number, phone number, and trader register name. * This information is available by passing `description` as `extras`. Example: ```json { "trader": { "address": { "address_line": "Keizersgracht 164", "city": "Amsterdam", "country": "nl", "post_code": "1015CZ" }, "email": "annemieke.hoteltoren@pavilionshotels.com", "name": "", "registration_number": "xxxxxxx", "telephone": "+311111111", "trade_register": "KVK" } } ``` | Demand API 3.1 | Update | Number of rooms | /accommodations/details | > **You can now check the total number of rooms in the property** * When calling the [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) endpoint you can see now information about the total number of rooms for a property. * This number is mostly used to determine the size and type of a property (with restrictions, see [accommodations/details guide](/demand/docs/accommodations/look-accommodation-details) for details). ### /orders/create endpoint | Demand API 3.1 | Update | IP Address for riskified | /orders/create | > **IP address is now a required field when sending order requests with Riskified authentication** * The `ip_address` field is now mandatory in [/orders/create](/demand/docs/open-api/demand-api/orders) endpoint for [Riskified authentication](/demand/docs/payments/payments-methods#credit-card--riskified) information used by external fraud verification. * This field is under payment-card-authentication-riskified: ```json { "payment": { "include_receipt": false, "card": { "number": "4242424242424242", "expiry_date": "2025-01", "cardholder": "io", "cvc": "111", "authentication": { "riskified": { "session_id": "00000000-0000-0000-0000-000000000000", "ip_address": "127.0.0.1" } } }, "timing": "pay_online_now", "method": "card" } } ``` ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Learn how to create your order using [riskified here](/demand/docs/payments/models/booking-collects#credit-card-non-sca--riskified). ## June 2024 | Demand API V3.1 | New features | Orders filters | US states | ### Orders/details endpoint > **You can now filter your orders by when an associated reservation started or ended, based on the checkin-checkout dates.** * We added the fields `start`and `end` together with the `to`- `from` strings to the [/order/details](/demand/docs/open-api/demand-api/orders/orders/details) endpoint. * This way you can retrieve orders with associated trips starting on a specific date range (which includes all the checkins that take place during that period.) or ending on a specific date range (which includes all the associated reservations checkouts done on that period). See examples and best practices in the [/order/details guide](/demand/docs/orders-api/order-details/) ### Accommodation endpoints > **We have added new features to adapt accommodation endpoints to new legislation in US** * You can specify the US state now by means of the optional `booker.state` field added to [/accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search), [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability), [/accommodations/bulk-availability](/demand/docs/open-api/demand-api/accommodations/accommodations/bulk-availability). * Currently, this is only applicable to United States. * For California users, partners must provide `ca` as the state value to comply with the new Price Display Legislation in this region. This legislation has now been superseded by the [FTC's national Rule on Unfair or Deceptive Fees](/demand/docs/compliance/ftc-compliance), which came into effect across the USA on 12th May 2025. ## May 2024 | Demand API V3.1 | New features > Accommodation ranking: - We added `ranking` in `/accommodations/details` which represent the public ranking of the accommodation calculated by the Booking ML team. - This ranking is a stripped version of the personalised ranking model on Booking.com (Note: This feature is not publicly available, need to be enabled for the partners upon request). > We added new features to locations/cities and location/districts endpoints: * Added `coordinates.latitude` and `coordinates.longitude` in [/common/locations/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities) and [/common/locations/districts](/demand/docs/open-api/demand-api/commonlocations/common/locations/districts) representing geographical coordinates of cities and districts. ## April 2024 | Demand API V3.1 | New accommodations/bulk-availability endpoint > These are the new features we added to Demand API V3.1: - New endpoint - [/accommodations/bulk-availability](/demand/docs/open-api/demand-api/accommodations/accommodations/bulk-availability) - You can now retrieve availability data for up to 50 accommodations with a single API request using `/accommodations/bulk-availability` endpoint. - Ability to filter results based on Cancellation Type (`free_cancellation`), Meal plans (`all_inclusive`, `breakfast_included`, `full_board`, `half_board`), Payment timings (`pay_at_the_property`,`pay_online`) and is Third-party inventory. ## February 2024 - Demand API V3.1 New release! > 🚀 **Version 3.1 released** with a wide range of new endpoints, some removals and changes. **New endpoints:** * [/common/payments/cards](/demand/docs/open-api/demand-api/commonpayments/common/payments/cards) - Returns a list of supported payments cards along with their English names. * [/orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) - Provides the total final price, final charges, price breakdown and payment/cancellation policies for each product in the input. Generates an `order_token` containing necessary data for subsequent requests to `/orders/create`. * [/orders/create](/demand/docs/open-api/demand-api/orders/orders/create) - Enables the creation of new orders. This endpoint must be used in conjunction with `/orders/preview`. After using `/orders/preview`, retrieve the `order_token` and pass it `/orders/create` for order creation. For detailed instructions, refer to our [endpoint usage guide](/demand/docs/orders-api/overview/). * [/orders/cancel](/demand/docs/open-api/demand-api/orders/orders/cancel) - Facilitates the cancellation of orders. * [/orders/details](/demand/docs/open-api/demand-api/orders/orders/details) - Returns information for orders based on specified filters. * [/orders/details/accommodations](/demand/docs/open-api/demand-api/orders/orders/details/accommodations) - Provides comprehensive information for specified accommodation orders. **Removed endpoints:** * `/common/payments/types` - This endpoint has been deprecated, and its functionality is integrated into [/common/payments/cards](/demand/docs/open-api/demand-api/commonpayments/common/payments/cards) for more unified experience. **Changes in** [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details): - Additions: - Added support for a new filter `payment.timing` to only return accommodation and blocks that contain the specified payment timings. Possible values - `pay_at_the_property`, `pay_online`. - Added `cots_and_extra_beds` to return the applicable price list of cots and extra beds. - Added `payment.methods` in the response which lists out payment methods accepted by this property. `payment.methods.cash` specifies if property accepts cash or not. `payment.methods.cards` return the list of cards accepted when paying at the property. - Added `payment.timings` in response to return Payment terms and conditions for the product. Possible values - `pay_at_the_property`, `pay_online_now`, `pay_online_later`. - Removals: - Removed `cots_and_beds`. Use `cots_and_extra_beds` instead. - Removed `payment.credit_card_requried`, `payment.cvc_required`, `payment.payment_types`. - Removed `name.fallback`. If a translation is missing in the selected language, the translated content will default to English language or the label entered by the property. - Removed `rooms[].name.fallback`. If a translation is missing in the selected language, the translated content will default to English language or the label entered by the property. - Removed `location.address.fallback`. If a translation is missing in the selected language, the translated content will default to English language or the label entered by the property. **Changes in** [/accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) - Additions: - Added support of a new filter `payment.timing` to only return accommodation and blocks that contain the specified payment timings. Possible values - `pay_at_the_property`, `pay_online`. - Added `policies.payment.timings` in the response to return Payment terms and conditions for this product. Possible values - `pay_at_the_property`, `pay_online_now`, `pay_online_later`. - Added new boolean field `third_party_inventory` in the response to provide information whether the product is facilitated by Booking.com partner company or not. - Changes: - Changed `dormitories` possible values to `include`, `exclude`, `only` from `true`, `false`. - Removals: - Removed `policies.payment.types`. Use `policies.payment.timings` instead. **Changes in** [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) - Additions: - Added support of a new filter `payment.timing` to only return accommodation and blocks that contain the specified payment timings. Possible values - `pay_at_the_property`, `pay_online`. - Added `maximum_occupancy.adults`, `maximum_occupancy.children`, `maximum_occupancy.total` in the response to provide information around maximum number of occupancy inside the room. Possible range of children allowed can be determined by `from_age`, `to_age` in `maximum_occupancy.children` object. - Added `policies.payment.timings` in the response to return Payment terms and conditions for this product. Possible values - `pay_at_the_property`, `pay_online_now`, `pay_online_later`. - Added new boolean field `third_party_inventory` in the response to provide information whether the product is facilitated by Booking.com partner company or not. - Removals: - Removed `number_of_adults`, `number_of_children`. Use maximum_occupancy object instead. - Removed `policies.payment.types`. Use `policies.payment.timings` instead. **Changes in** [/accommodations/constants](/demand/docs/open-api/demand-api/accommodations/accommodations/constants) - Removals: - Removed `charge_types[].name.fallback`, `accommodation_facilites[].name.fallback`, `accommodation_type[].name.fallback`, `room_facilites[].name.fallback`, `facilites_types[].name.fallback`, `room_types[].name.fallback`, `accommodation_themes[].name.fallback`, `review_scores[].name.fallback`, `bed_types[].name.fallback`, `bed_types[].description_imperial.fallback`. - If a translation is missing in the selected language, the translated content will be by default English language or the label entered by the property. **Changes in** [/common/locations/](/demand/docs/open-api/demand-api/commonlocations/) - Removed `data[].name.fallback`. - If a translation is missing in the selected language, the translated content will default to English language or the label entered by the property.