Pricing - use cases

This section provides examples of various accommodation requests and responses with pricing information for common use cases. These examples are designed to help you understand different pricing scenarios.

Conditional, included and excluded charges

City tax and cleaning fee

Below is an example of an /accommodations/availability response, which displays the included and excluded "extra_charges"

{
  ...
  "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 example, you can see the following price components:

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

Included and excluded charges

VAT included/ excluded

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

The following examples show how the response may differ, depending on the traveller's location based on the booker.country value.

Example: EU (Netherlands)

If the call originates from the Netherlands ("booker": {"country": "nl"}), EU law requires that VAT 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
      }
    }
  ]
}

In this example the Value Added Tax (charge=21) is calculated at 9% of the base price, resulting in a total_amount of 13.81.

• This means that 13.81 must be added to the base price, resulting in a "book" price of 167.21.

Example: US (United States) 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
  },
...
}

Incalculable charge

The following example illustrates the incalculable water usage fee (charge=10), which has no fixed value, as this depends on the consumption made during the stay.

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

Tourism fee

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

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

• The tourism fee (charge=142) is applied 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.

Conditional charges

Cleaning fees

In this example, a cleaning fee (charge=3) is applied on a per_stay basis, amounting to 25.00.

This fee will only be charged if the guests do not clean the room before check-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 request.

For example, in British Pounds (GBP):

{
...
"currency": "GBP",
...
"products": [
    "id": "xxxxxxxxx_xxxxxxxxx_x_x_x",
    "price": {
        "base": 153.40,
        "book": 167.21,
        ...

The currencycan either refer to:

• 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 be charged a different amount than originally shown.