Changelog

In accommodations/details endpoint

| New feature | Damage policy | Available to all partners |

We have introduced a damage policy in the /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 for the collection/refund.

Example:

    "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 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:

"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:

"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"
           ]
       },

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

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

Bug fixes

Demand API V3 all versions

| New features | New filter | All partners |

We have included the filterBy countries or cities options for /accommodations/details/changes endpoint.

• When using any of these filters in your /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.

Example with countries:

"last_change": "2024-09-29T17:00:00+00:00",
"filters": {
 "countries": [
   "nl",
   "es",
   "in"
]
}

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

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

| Update | Number of rooms | /accommodations/details |

You can now check the total number of rooms in the property

• When calling the /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.

| 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 endpoint for Riskified authentication information used by external fraud verification.
• This field is under payment-card-authentication-riskified:

"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"
},

Learn how to create your order using riskified here.

| Orders filters |

You can now filter your orders by when an associated reservation started or ended, based on the checkin-checkout dates.

• We added the fields startand end together with the to- from strings to the /order/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).

| US states |

We have also added new features to adapt accommodation endpoints to new legislation

• You can specify the US state now by means of the optional booker.state field added to /accommodations/search, /accommodations/availability, /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.

We added new features to locations/cities and location/districts endpoints:

• Added coordinates.latitude and coordinates.longitude in /common/locations/cities and /common/locations/districts representing geographical coordinates of cities and districts.

These are the new features we added to Demand API V3.1:

• New endpoint - /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.

Version 3.1 released with a wide range of new endpoints, some removals and changes.

New endpoints:

• /common/payments/cards - Returns a list of supported payments cards along with their English names.
• /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 - 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.
• /orders/cancel - Facilitates the cancellation of orders.
• /orders/details - Returns information for orders based on specified filters.
• /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 for more unified experience.

Changes in /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

• 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

• 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

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

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