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 - for example, seasonal deals such as Black Friday, or special rates for mobile users.
As a Demand API affiliate partner, you have access to specific incentives, allowing you to offer them to your customers. (If you need more information about the deals you can access, and any conditions on how to use them, contact your Account Manager).
In the Demand API, a deal
is a discounted product price that is available to a traveller when one or more of these incentives apply.
How to request deal information
When you call the /accommodations/search or /accommodations/availability endpoints, the following request values are used to determine what deals are available on the returned products:
- The API key used in the
Authorization: Bearer
header identifies the partner and affiliate IDs that you are using to make the request. Those IDs define what deals you have access to. checkin
andcheckout
: Include deals that are valid for the specified dates.booker
: Include deals that are only available if a traveller meets a specific condition. For example, they are logged in to your website or are using a mobile device.
For more details about how to return deal information, see the individual endpoint descriptions.
Example:
{ ... "booker": { "platform": "mobile", "country": "us", "user_groups": ["authenticated"] }, "checkin": "2023-09-01", "checkout": "2023-09-02", "extras": ["products"], ... }
Deal information in the response
The /accommodations/search or /accommodations/availability response contains details of any deals that are available on each returned product. The products.deal
response object returns the following information:
discount_percentage
- shows the total discount percentage that applies to the product'spublic_price,
after all qualifying deals have been applied.public_price
- shows the product's original price. This is the price to which thediscount_percentage
is applied. Note: The product's book price (price.book
) is thepublic_price
minus thediscount_percentage
.tags
- identifies the type(s) of deal that have been applied to the product.
If no deals are available, products.deal
returns null
.
The following example shows a product that has deals available for booking on a mobile device, and for booking during a specific period. The total value of the discount on these deals is 28%. This discount is applied to the product's original price of €100, giving a discounted book
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, },
The products.deal
object provides summary information about the available deals for a product, but does not provide a complete breakdown.
In some cases, it might not be obvious from the data returned exactly how the discount_percentage
value has been calculated. For example, if multiple deals apply, discounts may be applied sequentially. Alternatively, in cases where deals cannot be combined, the highest available discount would 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.
- If you display the
discount_percentage
you must display thepublic_price
as well - typically as a strikethrough price. - You must only show available discounts to eligible travellers - for example, only show
mobile_rate
discounts to travellers who are using an appropriate mobile device.
For example, suppose a call to /accommodations/search returned the following deal information about a product:
{ ... "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 show that information on the search results page like this.
Similarly, if you received the same information from a call to /accommodations/availability, you could show that information on the property page like this.