Changelog archive

Find here a comprehensive history of all updates, improvements, and bug fixes across versions.

Each entry provides a detailed log of changes made to Demand API, including new features, enhancements, and any resolved issues, divided by endpoints and/ or travel services.

This archive serves as a valuable resource for understanding the evolution of the product over time and tracking its progress.

Changelog - February 2025

Welcome to February 2025 changelog.

This month we've focused on improvements to orders and accommodation features in Demand API v3.1. These are some of the key highlights:

Orders

/orders/create

| Replacement | 3d secure authentication_value |

We have included the authentication_value field in the payment.card.authentication.3d_secure object within orders/create response.

• It accommodates 3D Secure's authenticationValue.
• It replaces cavv, which was used for the deprecated 3D Secure v1, a version no longer supported by Demand API V3.

Example:

"authentication": {
  "3d_secure": {
    "authentication_value": "AAAAAAAAAAAAAAA4l4AAAAAAAAA=",
    "eci": "05",
    "transaction": "00000000-0000-0000-0000-000000000000"
  }
}

| Addition | booker_address_required |

Previously when creating an order all fields of the booker.address object were mandatory. However, from now on only the country field is required:

"booker": {
  "address": {
    "country": "nl"
  }
}

The other fields within the booker.address object are subject to the value returned in the booker_address_required field within the accommodations/details response.

• If the /accommodations/details endpoint indicates that the booker's address is needed ( via the booker_address_required=true flag), the full address is mandatory in the orders/create request.
• If the booker_address_required flag is false, the booker's address can be omitted.

Example of accommodations/details response with booker_address_required=true

{
  "request_id": "01jmmjn081ta8d5a0kt83sgg1d",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "booker_address_required": true,
      "brands": [],
      "checkin_checkout_times": {...},

Example of orders/create response with booker.address filled:

"booker": {
    "address": {
      "address_line": "Road-1, house-2",
      "city": "Amsterdam",
      "country": "nl",
      "post_code": "11111"
    },

| Addition | confirmation id and checkin_number | third party inventory properties |

Two new fields have been included in the orders/create response for third-party inventory properties:

Example of the order response:

{
  "accommodation": {
    "order": "509430129718799",
    "pincode": "0000",
    "reservation": 12345678,
    "third_party_inventory": {
      "checkin_number": "123456789",
      "confirmation_number": "12345678912345678912"
    }
  }
}

/orders/preview

| Addition | inventory_type | third party inventory properties |

You can find now the inventory_type object in both accommodations/availability and orders/preview endpoints.

• This object indicates whether the property comes from a third-party inventory and the sort of rate that is applied, in this case "sell" rate:

Example of orders/preview response:

      "third_party_inventory": true,
      "inventory": {
        "third_party": true,
        "type": "sell"
      }  

Accommodation

accommodations/search

| Addition | product stock |

The number_available_at_this_price field indicates the available stock for each product ID (in units).

• It was already available in the /availability and /bulk-availability endpoints.
• Now you can also find it within the [/accommodations/search](accommodations/search response.

Example:

"products": [{
    "id": "1050736002_377311511_0_2_0",
    ...
    "maximum_occupancy": {
      "adults": 2,
      "children": null,
      "total": 2
    },
    "number_available_at_this_price": 10,
    ...
    "price": {
      "book": 184.00,
      "total": 184.00
    },
    "room": 1050736002
    ...

accommodations/details

| New functionality | DSA compliance | host_type and trader_verified |

We have added two new fields in the accommodations/details response, to comply with the Digital Services Act (“DSA”) legislation.

• host_type: Specifies the type of host for the accommodation (professional, private or unknown).
• trader_verified: Indicates whether the property has been successfully verified in line to Booking.com internal verification processes. This helps filter out non-verified properties for travellers in the European Economic Area (EEA), based on the booker's country.

These fields are available when requesting the /accommodations/details endpoint with the description extras parameter.

| Enhancement | Facilities details |

The following facilities-related information have been added in /accommodation/detail response:

Internet, parking, restaurant, swimming pool, together with specific details such as the type of connection, the charging model, pricing, location, reservation requirements, etc.

| Addition | meal_prices |

We have added meal_prices in accommodations/details response to indicate meal pricing for breakfast, lunch, and dinner:

Example:

{
  "meal_prices": {
    "breakfast": 20,
    "dinner": null,
    "lunch": null
  }
}

| Addition | domestic_no_cc |

We have included the domestic_no_cc field within the payment object.

• This indicates whether domestic bookers can book without using credit card for products offering free cancellation policies.

Example:

"payment": {
  "amex_cvc_required": false,
  "cvc_required": false,
  "domestic_no_cc": false,
  "methods": {
    "cards": [...],
    "cash": true,
    "virtual_cards": [
      1,
      2,
      3
    ]
  }
}

/accommodations/bulk-availability

| Addition | Cancellation schedule |

We have included the cancellation schedule within the policies.cancellation object in the /accommodations/bulk-availability response.

• This field provides the cancellation timeline and estimated pricing.

Example:

"policies": {
  "cancellation": {
    "free_cancellation_until": "2025-08-08T22:59:59+00:00",
    "type": "free_cancellation",
    "schedule": [
      {
        "from": "now",
        "price": 0
      },
      {
        "from": "2025-08-08T23:00:00+00:00",
        "price": 1189.63
      }
    ]
  }
}

Car rentals

cars/search

| Addition | payment_timing filter |

Users can now filter car rental search results based on payment timing options: pay_local, pay_now or part_pay.

Example of car rental search request with payment timing filter:

{
    "booker": {
        "country": "us"
    },
    "currency": "USD",
    "driver": {
        "age": 35
    },
    "route": {
        "pickup": {
            "datetime": "2025-07-21T10:00:00",
            "location": {
                "airport": "LAX"
            }
        },
        "dropoff": {
            "datetime": "2025-07-24T10:00:00",
            "location": {
                "airport": "LAX"
            }
        }
    },
    "payment": {
        "timings": ["pay_now", "part_pay"]
    }
}

Changelog - December 2024

Welcome to the final changelog of 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 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.

Example:

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

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

Orders/create

| New error messages | payment failures | orders/create | Available to all partners |

• When making a reservation using Payments through the 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.

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

You just need to pass "flights" as service when calling this endpoint:

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

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.

Example:

{
  "booker": {
    "external_account": 13610217,
    "platform": "mobile"
  }
}

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

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 returned in the orders/preview endpoint and that in the accommodations/availability endpoint.

November 2024

| Demand API V3.1 | New fields: deals, chargeable online | Minessota regulation | Orders |

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

Example:

{
  "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 section for all the details.

Example:

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

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

Example:

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

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.

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 under the "location" section:
  • The city id points to the city where the depot is located.

Example:

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

{
  "route": {
    "dropoff": {
      "datetime": "2024-11-10T11:05:00",
      "location": {
        "city": -393418
      }
    },
    "pickup": {
      "datetime": "2024-11-08T11:05:00",
      "location": {
        "city": -393418
      }
    }
  }
}

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

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

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

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

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

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

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

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

May 24th, 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 and /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
• 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 - 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.