Pricing in /accommodations

Learn how to retrieve product price information and display it on search results and property pages.

How to request price information

Use the /accommodations/search and /accommodations/availability endpoints to obtain detailed pricing information for the searched products included in the response.

Your application must present this information to travellers in a clear and consistent manner, adhering to all relevant laws and regulations, enabling them to make informed decisions before placing their orders.

Price information in the response

For each product, the products.price response object returns the following price components and their values:

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

In this examples, you can see the different 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.

→ Call the accommodations/constants endpoint to see the full list of charge type IDs so you can identify each charge.

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

Conditional charges

These are charges that apply only under specific conditions.

Some examples of conditional charges can be:

• Cleaning fee: A cleaning fee might be charged if the guest does not clean the room before checking out.

• Pet fee: A charge might be applied if the guest brings a pet. This fee is conditional on the presence of a pet during the stay.

• Smoking fee: A fee might be charged if the guest smokes in a non-smoking room. This charge is only applied if the guest violates the non-smoking policy.

• Late check-out fee: A fee might be charged if the guest checks out later than the agreed time. This charge is conditional on the guest's check-out time.

• Damage fee: A fee might be applied if there is damage to the property during the guest's stay. This charge is conditional on the occurrence of damage.

When there is a conditional charge, the condition field is displayed under the charge breakdown and identifies the sort of condition.

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 - VAT included/ excluded

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

Charge breakdown

Each charge type is defined in the appropriate category under extra_charges. Below are the fields used to describe each charge, including its purpose, amount, and calculation method.

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 - Incalculable charge

This is an example for incalculable water usage fee (charge=10).

...
"excluded": [
    {
        "charge": 10,
        "mode": "incalculable",
        "percentage": null,
        "total_amount": null,
        "unit_amount": null
    }
]
...

Example - Value Added Tax

In this example the 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 - Tourism fee

When the request specifies that 3 people are staying for 2 nights, and there is an extra charge for tourism fee, the response displays:

...
{
    "charge": 142,
    "mode": "per_person_per_night",
    "percentage": null,
    "total_amount": 15.42,
    "unit_amount": 2.57
}
...

• The tourism fee (charge=142) is charged on a per_person_per_night basis.
• As the request specified that 3 people are staying for 2 nights, the total_amount is calculated as (3 people) x (2 nights) x (unit_amount=2.57) = 15.42.

Example - Cleaning fee (conditional)

In this example, 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).

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.

• It might be the case that the price presented in the /accommodations/availability response is a bit different of that included in preview/order endpoint.
• Refer to Prices in orders page for more details about these pricing differences.