Deals

Learn how to request, return and display information about deals.

Booking.com offers different incentives to property owners to help them market their products such as seasonal deals (e.g. Black Friday) or special rates for mobile users.

As a Demand API Managed Affiliate Partner, you have access to specific incentives, which you can offer to your travellers.

If you need more information about the deals you can access to and how to use them, contact your Account Manager.

In the Demand API, a deal is a discounted product price available to a traveller when one or more incentives apply.

How to request deal information

Use the following endpoints to access deals information:

The following parameters determine the available deals for the returned products:

API key: The key used in the Authorization: Bearer header identifies the partner and affiliate IDs used to make the request. These IDs define the deals you have access to.
checkin and checkout: Include deals valid for the specified dates.
booker: Include deals that are only available if a traveller meets a specific condition. For example, they are authenticated users as they have logged in to your website or are using a mobile device.

Refer to the Search and Orders guidelines for instructions on how to define requests for these endpoints.

Example request

{
...
  "booker": {
    "platform": "mobile",
    "country": "us",
    "user_groups": ["authenticated"]
  },
  "checkin": "2023-09-01",
  "checkout": "2023-09-02",
  "extras": ["products"],
...
}

Deal information in responses

After calling to any of the before mentioned endpoints, the response contains the products.deal object, where you can look at available deals.

discount_percentage - The total discount percentage applied to the product's public_price after all qualifying deals are factored in.
public_price - The original price of the product, before discounts. This is the price to which the discount_percentage is applied.

The product's book price (price.book) is the public_price minus the discount_percentage.

tags - Identifies the types of deals applied to the product.

If no deals are available, products.deal returns null.

Example of response

The following example shows a product eligible for a 28% discount, applicable when booking via a mobile device or during a specific promotional period.

The original price is €100, resulting in a discounted price of €72.00.

{
  ...
  "currency": "EUR",
  ...
  "products": [
    ...
    "id": "xxxxxxxx_x_xxxxxxxxx_x_x_x",
    "deal": {
      "discount_percentage": 28,
      "public_price": 100.00,
      "tags": [
        "mobile_rate",
        "limited_time_deal"
      ]
    },
    ...
    "price": {
      "book": 72.00,
    },

Tags and discount_percentage

The products.deal object provides summary information on available deals for a product. However, it does not always give a detailed breakdown of how the discount_percentage is calculated.
If multiple deals apply, discounts may be applied sequentially.
Alternatively, if deals cannot be combined, only the highest available discount will be returned.

How to display deal information

You can use the information from the products.deal object to show that a deal is available on a product.

Displaying deals

If you display the discount_percentage you must also display the public_price - typically as a strikethrough price.
You must only show available discounts to eligible travellers - for example, only show mobile_rate discounts to travellers using an appropriate mobile device.

Display example

For instance, if a call to /accommodations/search returns the following deal information:

{
  ...
  "currency": "EUR",
  ...
  "products": [
    ...
    "id": "xxxxxxxx_x_xxxxxxxxx_x_x_x",
    "deal": {
      "discount_percentage": 45,
      "public_price": 1005.00,
      "tags": [
        "limited_time_deal"
      ]
    },
    ...
    "price": {
      "book": 553.00,
    },

You could showcase this on the search results page as follows:

Limited Time Deal Search

Similarly, if you receive the same information from a call to /accommodations/availability, you can display it on the property page like this:

Limited Time Deal Availability

For more information on setting up search requests and looking at availability, explore the Search for accommodation section.
Refer to the Search use cases section for more practical examples.
Look at the Create orders guidelines for instructions on how to define requests for orders/preview endpoint.