Prices and extra charges - use cases

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

Chargeable online - Knowing what Booking.com will collect

When using Booking.com’s online payment methods (e.g. pay_online_now, pay_online_later), the chargeable_online field helps you determine which parts of the booking price will be collected online by Booking.com, versus what the traveller must pay at the property.

This is crucial for:

Displaying accurate payment breakdowns to travellers.
Correctly loading Virtual Credit Cards (VCCs).
Avoiding overcharging or payment mismatches in your integration.

Where you'll find it

price.chargeable_online: The total amount Booking.com will charge online (in both accommodation and booker currencies).
extra_charges.non_conditional[].chargeable_online: Indicates, for each non-optional charge, whether Booking.com will collect it online (true) or it must be paid on-site (false).

Use case: Splitting online and on-property charges

Scenario: You want to show travellers what they will pay now vs what they will pay later at the property.

API response:

            {
  "price": {
    "base": {
      "accommodation_currency": 110.03,
      "booker_currency": 110.03
    },
    "extra_charges": {
      "conditional": [],
      "non_conditional": [
        {
          "charge": 22,
          "chargeable_online": false,
          "mode": "per_person_per_night",
          "percentage": null,
          "total_amount": {
            "accommodation_currency": 4.50,
            "booker_currency": 4.50
          },
          "unit_amount": {
            "accommodation_currency": 4.50,
            "booker_currency": 4.50
          }
        },
        {
          "charge": 21,
          "chargeable_online": true,
          "mode": "percentage",
          "percentage": 10.00,
          "total_amount": {
            "accommodation_currency": 11.00,
            "booker_currency": 11.00
          },
          "unit_amount": {
            "accommodation_currency": null,
            "booker_currency": null
          }
        }
      ]
    },
    "chargeable_online": {
      "accommodation_currency": 121.03,
      "booker_currency": 121.03
    },
    "total": {
      "accommodation_currency": 125.53,
      "booker_currency": 125.53
    }
  },
  "room": 438312701
}

How to interpret this:

The first non_conditional extra charge with ID 22 (Laundry) is not chargeable online by Booking.com, as it is marked as "false" - 4.50 will be paid directly at the property.
The second non_conditional extra charge with ID 21 (Babysitting/child services) is chargeable online by Booking.com, as is set to "true" - 11 will be collected online by Booking.com.

Total price for the traveller: 125.53 (price.total.booker_currency)
Booking.com will collect online: 121.03 (price.chargeable_online.booker_currency)

You can display this as:

You’ll pay 121.03 now via Booking.com. An additional 4.50 for laundry is payable at the property.

Important considerations

The chargeable_online fields are only relevant for online payment flows such as pay_online_later or pay_online_now.
These fields are ignored if the traveller uses the pay_at_the_property timing — in that case, all charges are handled directly by the property, and no amount is collected by Booking.com.

Important

If your integration uses pay_at_the_property, do not rely on chargeable_online values. All charges — including mandatory extras — must be settled at the property.

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:

Component	Amount	Description
Base price	£153.40	The basic price of the product.
Book price	£167.21	The price the traveller must pay to reserve this product: The `included` extra charge is VAT (`"charge": 21`) totalling £13.81. Thus, the `book` price is £153.40 + £13.81 = £167.21.
Total price	£168.74	The final price the traveller must pay for this product: There is an `excluded` extra charge for city tax (`"charge": 22`) totalling £1.53. Therefore, the `total` price is £167.21 + £1.53 = £168.74.
Extra charges	£25.00 (only if)	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` extra charge -- there 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`). `excluded` extra charge -- There is a water usage fee (`charge`=`10`), with an undefined value (`"mode": "incalculable"` and `"total_amount": null`) The traveller will have to pay some extra amount based on the amount of water they use during their stay.

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

Important note

The base and total prices remain unchanged in both cases, regardless of the inclusion or exclusion of VAT.

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.

Next steps

Looking to implement or optimise pricing display and booking flows? Here are some helpful resources: