Prices (/accommodations)
Learn how to get information about product prices and display it on search results and property pages
The /accommodations/search and /accommodations/availability endpoints return price information about the products included in their responses. Your application must display this price information to travellers clearly, consistently and in accordance with all relevant laws and regulations, so that they can decide if they want to proceed and place an order.
If your application also handles the order process, you should be aware that the /orders
endpoints return price information slightly differently to the /accommodations
endpoints. See Prices (/orders) for more information about these differences.
How to request price information
For more details about how to request the price information that you want in a particular call, see the individual endpoint descriptions.
Price information in the response
For each product, the products.price
response object returns the following price components and their values:
base
: The basic price. This price excludes allextra_charges
.extra_charges
: Costs that are added to thebase
price - for example, city taxes, value added tax (VAT), cleaning fees or additional parking fees. Each charge is assigned to one of the following categories:included
: Non-conditional charges that are included in thebook
price.excluded
: Non-conditional charges that are excluded from thebook
price. (Exception: incalculable charges are excluded from thetotal
price).conditional
: Charges that only apply under certain conditions. These are always excluded from thebase
,book
andtotal
prices.
book
: The price that the traveller must pay to reserve this product. This equals thebase
price plusincluded
extra_charges
.total
: The price that the traveller must definitely pay for this product. This equals thebook
price plusexcluded
extra_charges
.
Note:
- The traveller might have to pay additional conditional or incalculable charges in addition to the
total
price. - The
price
object defines what the traveller will or might have to pay, but does not define when or how they must pay. See Payments for more information.
An example
The following example shows part of an /accommodations/availability response.
{ ... "currency": "GBP", ... "products": [ "id": "xxxxxxxxx_xxxxxxxxx_x_x_x", "price": { "base": 153.40, "book": 167.21, "extra_charges": { "conditional": [{ "charge": 3, "condition": 28 "mode": "per_stay", "percentage": null, "total_amount": 25.00, "unit_amount": 25.00 }], "excluded": [{ "charge": 10, "mode": "incalculable", "percentage": null, "total_amount": null, "unit_amount": null } { "charge": 22, "mode": "percentage", "percentage": 1.00, "total_amount": 1.53, "unit_amount": null }], "included": [{ "charge": 21, "mode": "percentage", "percentage": 9.00, "total_amount": 13.81, "unit_amount": null }] }, "total": 168.74 }, ... }
The different price components are calculated as follows:
- base price: £153.40. The basic price of the product.
- book price: £167.21. What the traveller must pay to reserve this product:
- There is an
included
extra charge, which is VAT ("charge": 21
) with a total cost of ("total_amount": 13.81
). book
price is therefore £153.40 + £13.81 = £167.21.
- There is an
- total price: £168.74. What the traveller must definitely pay for this product:
- There is an
excluded
extra charge with a defined value, which is a city tax ("charge": 22
) with a total cost of ("total_amount": 1.53
). total
price is therefore £167.21 + £1.53 = £168.74.
- There is an
- Additional charges: Unknown. Conditional or incalculable costs that the traveller might have to pay for this product in addition to the
total
price:- There is a
conditional
extra charge, which is a cleaning fee ("charge": 3
) with a total cost of ("total_amount": 25.00
). The traveller will pay an extra £25.00 if they do not clean the room before they leave ("condition": 28
). - There is an
excluded
extra charge with an undefined value ("mode": "incalculable"
and"total_amount": null
), which is a water usage fee (charge
=10
). The traveller will have to pay some extra amount based on the amount of water they use during their stay.
- There is a
Included and excluded charges
Different countries have different legal requirements on how prices should be shown to consumers - for example, whether value-added tax (VAT) should be included or excluded.
To ensure compliance with all applicable requirements, Booking.com determines whether each non-conditional charge should be included
or excluded
when returning price information. The decision takes into account the countries in which both the traveller and the requested products are located. Note that, as a result:
- A charge on a product may appear as
included
when you expect it to appear asexcluded
, or vice versa. - The
book
price for the same product, with the same request criteria, may vary depending on the origin of the request.
An example
Suppose a traveller's search response contains a product on which VAT ("charge": 21
) must be paid. In the EU, VAT must be included in the price shown to consumers. In the US, VAT is not included. The following fragments show how the response can differ, depending on which country the traveller is in when they make the request (taken from the booker.country
value).
If the call originates from the Netherlands ("booker": {"country": "nl"}
), EU law applies so the VAT charge is included in the book price:
{ ... "products": [ "id": "xxxxxxxxx_xxxxxxxxx_x_x_x", "price": { "base": 153.40, "book": 167.21, "extra_charges": { "conditional": [], "excluded": [], "included": [ { "charge": 21, "mode": "percentage", "percentage": 9.00, "total_amount": 13.81, "unit_amount": null }, ... ] }, "total": 167.21 }, ... }
If the call originates from the US ("booker": {"country": "us"}
), the VAT charge is excluded, resulting in a lower book
price.
{ ... "products": [ "id": "xxxxxxxxx_xxxxxxxxx_x_x_x", "price": { "base": 153.40, "book": 153.40, "extra_charges": { "conditional": [], "excluded": [ { "charge": 21, "mode": "percentage", "percentage": 9.00, "total_amount": 13.81, "unit_amount": null }, ... ] "included": [] }, "total": 167.21 }, ... }
Note that the base
and total
prices remain the same in both cases.
Conditional charges
A product can have charges that apply only under certain conditions:
- The
condition
field in the charge breakdown defines the condition under which the charge applies. - The charge appears in the
conditional
category, and is always excluded from thebase
,book
andtotal
prices.
Conditional charges are typically paid at the property by the traveller at checkout.
Charge breakdown
A definition of each charge is provided in the appropriate category under extra_charges
. The following fields in the definition identify what the charge is for, how much it is and how it is calculated.
Field | Description |
---|---|
charge | Unique id of the charge type.Use /accommodations/constants to obtain the charge name associated with this id . |
condition | Unique id of the condition that applies to this conditional charge . See Condition ids for the description of the condition. Note: This field is only shown for conditional charges. |
mode | Enumerated value that identifies the basis on which the charge is applied, and how the total_amount for the charge is calculated. See Charge modes. |
percentage | If mode is percentage , this is the percentage value at which the charge is applied (against the price.base value),If mode is any other value, this value is null . |
total_amount | Total price for the charge. See Charge modes. |
unit_amount | If mode is per_night , per_person_per_night , or per_person_per_stay , this value is the price per unit for the charge,If mode is any other value, this value is null . |
Charge calculation
The charge_mode
value identifies the basis on which the charge is applied, and how the total_amount
for the charge is calculated.
charge_mode value | total_amount value |
---|---|
calculated_amount | Value of the charge |
incalculable | null Note: An incalculable charge always appears in the extra_charges.excluded category. |
percentage | Calculated as percentage * base price |
per_night | Calculated as unit_amount * number of nights |
per_person_per_night | Calculated as unit_amount * number of guests * number of nights |
per_person_per_stay | Calculated as unit_amount * number of guests |
per_stay | Value of the charge |
Condition ids
The following table shows the condition
ids that can be returned in each charge breakdown, along with their description and the charges that they can be applied to.
condition id | Description | Applies to charge_types (ids) |
---|---|---|
5 | A fee is applicable if you do not bring your own items. | TOWELFEE (4), BEDLINEN (6), LINENPACKAGEFEE (100), KITCHENLINNENFEE (103) |
28 | A cleaning fee will be charged if you don't clean before checking out. | CLEANINGFEE (3) |
29 | A cleaning fee is applicable, per pet, if you bring your pet to the accommodation. | CLEANINGFEE (3) |
30 | A cleaning fee is applicable if you smoke in the accommodation. | CLEANINGFEE (3) |
35 | A fee is applicable if you use a credit card of any type. | CREDITCARDFEE (116) |
37 | A fee is applicable if you use a credit card of a specific type. | CREDITCARDFEE (116) |
39 | A fee is applicable if you use a credit card of a list of types. | CREDITCARDFEE (116) |
126 | An internet fee is applicable if you use it, per hour of use. | INTERNETFEE (118) |
136 | Parking fee - start time to end time | PARKINGFEE (119) |
142 | Parking fee - day of week | PARKINGFEE (119) |
210 | Mandatory Israel VAT for domestic users | VAT (21) |
211 | Optional Israel VAT for all users | VAT (21) |
215 | A fee is applicable if you use the indicated facility. | SPA (180), SAUNA (181), HOTTUB (182), GOLFCOURSE (199), SUNBED (200), POOL (204) |
504 | A city tax is applicable. Business travellers can be exempt from this charge under certain conditions. Please check the city's official website for details prior to arrival. | CITYTAX (22) |
542 | A city tax is applicable if you are an adult. | CITYTAX (22) |
543 | A city tax is applicable for a maximum of n consecutive nights. Further consecutive nights at the same accommodation are exempt. | CITYTAX (22) |
Charge examples
Example 1: An incalculable
water usage fee (charge
=10
).
... "excluded": [ { "charge": 10, "mode": "incalculable", "percentage": null, "total_amount": null, "unit_amount": null } ] ...
Example 2: Value Added Tax (charge
=21
) is charged at 9% of the base
price, giving a total_amount
of 12.47
.
... { "price": { "base": 138.56, ... "extra_charges": { ... { "charge": 21, "mode": "percentage", "percentage": 9.00, "total_amount": 12.47, "unit_amount": null }, ...
Example 3: A tourism fee (charge
=142
) is charged on a per_person_per_night
basis. The request specified that 3 people are staying for 2 nights, so the total_amount
is calculated as (3 people) * (2 nights) * (unit_amount
=2.57
) = 15.42
.
... { "charge": 142, "mode": "per_person_per_night", "percentage": null, "total_amount": 15.42, "unit_amount": 2.57 } ...
Example 4: A cleaning fee (charge
=3
) is charged on a per_stay
basis, at a cost of 25.00
. The fee will only be charged if the guests do not clean the room before checking out (condition
=28
).
... "conditional": [ { "charge": 3, "condition": 28, "mode": "per_stay", "percentage": null, "total_amount": null, "unit_amount": 25.00 } ] ...
Currencies
All prices are shown in the currency
defined in the response. For example:
{ ... "currency": "GBP", ... "products": [ "id": "xxxxxxxxx_xxxxxxxxx_x_x_x", "price": { "base": 153.40, "book": 167.21, ...
The currency
value is either:
- The accommodation currency, which is the currency used by the provider of the returned product, and the currency the traveller will pay in. This is the default option.
- The booker currency, which is the currency requested by the traveller performing the search (in the request
currency
field).
If the two currencies are different, the booker currency value shows the converted value of the accommodation currency, based on the current exchange rate available to Booking.com. If the exchange rate changes before the traveller completes the order, they will pay a different price to the one shown.
How to display price information
Your application must display price information to travellers clearly, consistently and in accordance with all relevant laws and regulations. The following sections provide some advice on how to do this on search results and property pages.
Prices display
- Display the price of a product or product group using the appropriate
book
price. - If you display a
book
price that is discounted because a deal is available, you can show details of the deal. See How to display deal information. - Clearly indicate whether a
book
price includes taxes and charges, and whether any additional charges will or might apply. For example, label the price with a short message such as "Includes taxes and charges" or 'Additional charges may apply". For example:
Excluded charges display
If you show details of excluded
charges:
- Display details of each
excluded
charge individually. Do not combine them into your own categories. - For each charge, display the charge
name
(from /accommodations/constants) andmode
, and either thepercentage
value, or thetotal_amount
andcurrency
, as appropriate. - Do not display specific details for any
incalculable
charges.
For example (on a property page):
Conditional charges display
If you show details of conditional
charges, either provide a detailed explanation for each charge individually, or simply include them as part of an 'Additional charges may apply" message.
Application flow consistency
Make sure that the information you display is consistent across each stage of your integration flow:
- If you redirect travellers to Booking.com from a search results or property page, your information must be consistent with the page that you redirect the user to.
- If your application handles the order process itself, your information must be consistent with what you show on your orders page. See Prices (/orders).