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

Different price in availability and orders

If your application also handles the order process, note that the /orders endpoints return price information slightly differently to the /accommodations endpoints.

For more details on these differences, see Pricing in /orders.

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

• extra_charges: Additional costs added to the base price - for example, city taxes, value added tax (VAT), cleaning fees or additional parking fees.

  These charges are categorised as:

  • included: Non-conditional charges that are included in the book price.
  • excluded: Non-conditional charges that are excluded from the book price. (Exception: incalculable charges are excluded from the total price).
  • conditional: Charges that only apply under certain conditions. These are always excluded from the base, book and total prices.

• book: The price that the traveller must pay to reserve this product. This equals the base price plus included extra_charges.

• total: The price that the traveller must definitely pay for this product. This equals the book price plus excluded extra_charges.

Example

Here's an example 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
    },
    ...
  }

Explanation of price components

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

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

• Additional charges: Travellers may need to pay conditional or incalculable charges, such as a cleaning fee or water usage fee, on top of 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.

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 as excluded, or vice versa.
• The book price for the same product, with the same request criteria, may vary depending on the origin of the request.

Example

If a traveller in the EU requests a product, VAT ("charge": 21) is included in the book price. For the same product requested from the US, VAT is excluded.

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

These are charges that apply only under specific conditions.

• The condition field in the charge breakdown defines the condition under which the charge applies.
• They are always excluded from the base, book and total prices and are typically paid 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.

Charge calculation modes

The charge_mode value identifies the basis on which the charge is applied, and how the total_amount for the charge is calculated.

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.

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.

Displaying 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) and mode, and either the percentage value, or the total_amount and currency, 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).