Last updated

Accommodation pricing

Learn about the accommodation price information retrieved in the search, availability and order endpoints, and how to display it correctly in your platform.

Requesting price information

Use the following endpoints to access accommodation pricing information:

EndpointUse it to...Best practice

/accommodations/search /accommodations/availability

✓ Obtain detailed pricing information for the accommodation products included in the response.

✓ Don't forget to include the "products" and "extra_charges" fields in the "extras" object of your request.

✓ Make sure you present the appropriate price including rates/deals based on the user’s eligibility.

/orders/preview✓ Before finalising the booking, review the detailed pricing information to ensure they are correct.✓ Your application must display 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.

Refer to the Search and availability , and Orders guides for specific instructions on how to make requests to these endoints so all extra charges are returned in the responses.

Pricing in responses

When querying for availability or searching for accommodation, and also when previewing the order before processing the booking, the responses retrieve a product.price object that defines what the traveller will or might have to pay.

However, you cannot find here when or how they must pay, for this information see the Payments section.

The product.price object displays the price breakdown with different fields and their values.

Note there are slightly different parameters in the accommodations/search and availability responses, and those offered in orders/preview response.

In accommodation/search and availability

Fields
Description
baseThe basic price -- This price excludes all extra_charges.
bookThe book price that the traveller must pay to reserve this product.
  • This equals the base price + included extra_charges.

extra_charges

Additional costs that are applied to the base price.

These are categorised as:

  • conditional -- only applied under certain conditions. Always excluded from base and book prices. For example the cleaning fee.

  • included -- those added to the book price.

  • excluded -- not included in the book price.

    (Exemption: Incalculable charges are excluded from the total price)

totalThe final amount the traveller must pay for the product even when paying up-front.
  • This equals the book price + excluded and non_conditional extra_charges.
  • The total price is returned in both, the accommodation and booker currencies, which may differ slightly based on the currency used.
Important

The traveller may have to pay additional conditional or incalculable charges in addition to the total price.

Example accommodation/availability response

Here's an example of an /accommodations/availability response, with 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 examples, you can see the following price components: Base, book and total price, as well as extra conditional, excluded and included charges.

See the full explanation for this example in the Pricing use cases section.

In orders/preview

The pricing breakdown returned by the /orders/preview endpoint also includes the base and total prices. However it includes other parameters:

Field Description
extra_charges
  • The exclusive or inclusive categories used in the /accommodations/ responses are not applicable to the order process.
  • Instead, all exclusive or inclusive charges are defined as non_conditional.
  • These are the charges that must be unconditionally paid and are always included in the total price. (Exemption: incalculable charges are excluded from the total price).
chargeable_online
  • This field specifies the amount that will be charged online by Booking.com. This amount will always be less than or equal to the total price.
  • Note: This applies only if Booking.com is managing partner payments.
book
  • This value is not longer needed in the orders/preview response.
  • Book price is not returned in orders responses.

Example orders/preview response

"price": {
        "base": {
          "accommodation_currency": 100,
          "booker_currency": null
        },
        "chargeable_online": {
          "accommodation_currency": 100,
          "booker_currency": null
        },
        "total": {
          "accommodation_currency": 123,
          "booker_currency": null
        },
        "extra_charges": {
          "conditional": [],
          "non_conditional": [
            {
              "charge": 142,
              "chargeable_online": true,
              "total_amount": {
                "accommodation_currency": 6,
                "booker_currency": null
              }
            },
            {
              "charge": 21,
              "chargeable_online": false,
              "total_amount": {
                "accommodation_currency": 14.67,
                "booker_currency": null
              }
            },
            {
              "charge": 22,
              "chargeable_online": true,
              "total_amount": {
                "accommodation_currency": 11.41,
                "booker_currency": null
              }
            }
          ]
        }
      },
  • The book price is not visible, as this is no longer needed to be displayed before booking.
  • The non_conditional additional charges indicate the final charges that have been included in the total price and must be paid to proceeed the booking.
  • 100 out of 123 of the total price, will be charged by Booking online.

Chargeable online

The chargeable_online field, is present in both the accommodation price summary and the product list price, and also under extra_charges.non_conditional.

  • This field indicates whether the specific extra charge, which must be paid unconditionally and included in the total price, is chargeable by Booking.com.

    • Chargeable refers to charges that Booking.com is responsible to proceed.

  • When this field is set to "true" under the extra_charges.non_conditional, the chargeable amount is included in the response, provided in both the booker and accommodation currencies.

Example - chargeable price

In this example:

  • The first non_conditional extra charge with ID 22 (Laundry) is not chargeable online by Booking.com, as it is marked as "false".

  • The second non_conditional extra charge with ID 21 (Babysitting/child services) is chargeable online by Booking.com, as is set to "true".

    • The price to be charged online for this extra charge is 11.00.

    • The total amount that Booking.com will charge online is 121.03, out of 125.53.

            {
  "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
}

Important considerations

This field is only relevant when Booking.com is managing the payments using online payment timings such as pay_online_later or pay_online_now.

  • For these timings, certain charges will be marked as chargeable, while others will not.
  • The non-chargeable charges must be paid directly at the property.
Important

If you use pay_at_the_property payment timing, please disregard any chargeable_online fields present in the response, as any charges are handled by the property and not by Booking.com.

Currency representation

All prices and amounts are displayed in both the accommodation_currency and the booker_currency.

If the currency is not defined in the search or availability request, the booker_currency value in the response is null.

Example with different currencies

In the following orders/preview response, the traveller is located in England, hence the booker currency defaults to Pounds (GBR).

The accommodation is located in Spain so the accommodation currency presents the amount in Euros (EUR).

Therefore all charges are displayed in both currencies.

{
  "accommodation": {
    "id": "xxxxxxxx",
    "currency": {
      "accommodation": "EUR",
      "booker": "GBP"
    },
    "price": {
      "base": {
        "accommodation_currency": 82.57,
        "booker_currency": 70.85
      },
      "extra_charges": {
        "conditional": [],
        "non_conditional": [
          {
            "charge": 21,
            "total_amount": {
              "accommodation_currency": 7.43,
              "booker_currency": 6.38
            }
          },
          {
            "charge": 22,
            "total_amount": {
              "accommodation_currency": 2.00,
              "booker_currency": 1.72
            }
          }
        ]
      },
      "total": {
        "accommodation_currency": 92.00,
        "booker_currency": 78.95
      }
    }
  }
}

Extra charges

Extra charges are additional costs that are applied to the base price - for example, city taxes, value added tax (VAT), cleaning fees or additional parking fees.

  • Travellers may need to pay conditional, or incalculable charges, such as a cleaning fee or water usage fee, on top of the total price.

  • When reviewing the order, there might also be non_conditional charges that will be included in the total amount and must be unconditionally paid.

Extra charges disclosure

Each extra charge is defined in the appropriate category under extra_charges.

These are the fields used to describe each extra charge category, including its purpose, amount, and calculation method.

Field DescriptionRecommmendation

charge

This field is linked to an uniquely number identifier that represents the charge type.

Use /accommodations/constants to obtain the charge name associated to this number.

Example: city tax is "charge": 22

condition

A number that uniquely identifies the condition that applies to this conditional charge.

See the full list of conditions and equivalent conditional change, in the Condition ids section.

This field is only displayed for conditional charges.

modeThe basis for applying the charge, such as percentage or per night.See Charge calculation modes for more details.
percentageIf the mode is percentage, this field indicates the value percentage at which the charge is applied (against the price.base value).If mode is any other value, the percentage value is null.
unit_amountIf 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.
total_amountThe total amount to be paid for the charge.It is always defined for excluded and included charges, but it is null for incalculable charges.

Charge type ID

All extra charges are grouped by charge type, that is identified by an ID. Examples of extra charges are: VAT, City Tax, etc.

Example: In the following Orders/preview response the extra charge types are identified with these ids: 3, 142, 21 and 22.

{
  "price": {
    "base": {
      "accommodation_currency": 162.98,
      "booker_currency": null
    },
    "extra_charges": {
      "conditional": [
        {
          "charge": 3,
          "condition": 30,
          "mode": "per_stay",
          "percentage": null,
          "total_amount": {
            "accommodation_currency": 10,
            "booker_currency": null
          },
          "unit_amount": null
        }
      ],
      "non_conditional": [
        {
          "charge": 142,
          "chargeable_online": false,
          "mode": "per_person_per_night",
          "percentage": null,
          "total_amount": {
            "accommodation_currency": 6,
            "booker_currency": null
          },
          "unit_amount": {
            "accommodation_currency": 3,
            "booker_currency": null
          }
        },
        {
          "charge": 21,
          "chargeable_online": true,
          "mode": "percentage",
          "percentage": 9,
          "total_amount": {
            "accommodation_currency": 14.67,
            "booker_currency": null
          },
          "unit_amount": null
        },
        {
          "charge": 22,
          "chargeable_online": false,
          "mode": "percentage",
          "percentage": 7,
          "total_amount": {
            "accommodation_currency": 11.41,
            "booker_currency": null
          },
          "unit_amount": null
        }
      ]
    },
    "total": {
      "accommodation_currency": 195.06,
      "booker_currency": null
    }
  }
}

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

For the given example, the accommodations/constants response retrieves:

  [
  {
    "id": 3,
    "name": {
      "en-gb": "Restaurant"
    }
  },
  {
    "id": 21,
    "name": {
      "en-gb": "Babysitting/child services"
    }
  },
  {
    "id": 22,
    "name": {
      "en-gb": "Laundry"
    }
  },
  {
    "id": 142,
    "name": {
      "en-gb": "Child safety socket covers"
    }
  }
]
Best practice - caching constants
  • Since /accommodations/constants endpoint returns static data, we recommend caching the response and refreshing the cache daily.
  • This will help reduce traffic to the endpoint and improve response times, ensuring more efficient use of resources.

Charge calculation mode

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_amountValue of the charge.
incalculablenull
Note: An incalculable charge always appears in the extra_charges.excluded category.
percentageCalculated as percentage x base price.
per_nightCalculated as unit_amount x number of nights.
per_person_per_nightCalculated as unit_amount x number of guests x number of nights.
per_person_per_stayCalculated as unit_amount x number of guests.
per_stayValue of the charge.

Conditional charges

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

Example:

In this example, there is a condition 28 and charge 3. Looking at the Condition ids mapping, this refers to:

  • 28 - A cleaning fee will be charged if you don't clean before checking out.
  • 3 - CLEANINGFEE charge.
{
  "extra_charges": {
    "conditional": [
      {
        "charge": 3,
        "condition": 28,
        "mode": "per_stay",
        "percentage": null,
        "total_amount": 25.00,
        "unit_amount": 25.00
      }
    ]
  }
}

Some other conditional charges can be:

  • Pet fee - Applied if the guest brings a pet to the stay.

  • Smoking fee - Charged if the guest smokes in a non-smoking room.

  • Late checkout fee - Applied if the guest checks out later than the agreed time.

  • Damage fee - Charged if there is damage to the property during the stay.

Important

Conditional charges are always excluded from the base, book and total prices, as (if applicable) they are typically paid by the traveller at checkout.

Condition ids

The following table shows the condition ids that can be returned in each charge breakdown, along with their description and the charge type that they can be applied to.

Condition idDescriptionApplies to charge_types (ids)
5A fee is applicable if you do not bring your own items.TOWELFEE (4), BEDLINEN (6), LINENPACKAGEFEE (100), KITCHENLINNENFEE (103)
28A cleaning fee will be charged if you don't clean before checking out.CLEANINGFEE (3)
29A cleaning fee is applicable, per pet, if you bring your pet to the accommodation.CLEANINGFEE (3)
30A cleaning fee is applicable if you smoke in the accommodation.CLEANINGFEE (3)
35A fee is applicable if you use a credit card of any type.CREDITCARDFEE (116)
37A fee is applicable if you use a credit card of a specific type.CREDITCARDFEE (116)
39A fee is applicable if you use a credit card of a list of types.CREDITCARDFEE (116)
126An internet fee is applicable if you use it, per hour of use.INTERNETFEE (118)
136Parking fee - start time to end timePARKINGFEE (119)
142Parking fee - day of weekPARKINGFEE (119)
210Mandatory Israel VAT for domestic usersVAT (21)
211Optional Israel VAT for all usersVAT (21)
215A fee is applicable if you use the indicated facility.SPA (180), SAUNA (181), HOTTUB (182), GOLFCOURSE (199), SUNBED (200), POOL (204)
504A 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)
542A city tax is applicable if you are an adult.CITYTAX (22)
543A city tax is applicable for a maximum of n consecutive nights. Further consecutive nights at the same accommodation are exempt.CITYTAX (22)

Included and excluded charges

Booking.com adjusts charges based on legal requirements in different countries, determining whether non-conditional charges should be included or excluded in price information.

This decision depends on the locations of both the traveller and the product. As a result:

  • A charge on a product may appear as included or excluded based on local regulations.
  • The book price for the same product, with the same request criteria, may vary depending on the origin of the request.

These fields are only retrieved when calling accommodation/search and availability endpoints.

Non conditional charges

When querying the /orders/preview endpoint, the response returns the products.price object with similar pricing details for each product within the order, including a detailed breakdown of extra charges.

However, in orders, the included/excluded extra charges turn into non_conditional charges. These are the extra charges that must be unconditionally paid.

Example:

{
  "extra_charges": {
    "conditional": [],
    "non_conditional": [
      {
        "charge": 142,
        "chargeable_online": true,
        "mode": "per_person_per_night",
        "percentage": null,
        "total_amount": {
          "accommodation_currency": 6,
          "booker_currency": null
        },
        "unit_amount": 3
      },
      {
        "charge": 21,
        "chargeable_online": false,
        "mode": "percentage",
        "percentage": 9,
        "total_amount": {
          "accommodation_currency": 14.04,
          "booker_currency": null
        },
        "unit_amount": null
      }
    ]
  }
}

Price variations

There may be slight discrepancies between the pricing presented in the /accommodations/availability response and that included in preview/order endpoint.

When discrepancies occur:

  • The price returned by the preview response should be the one utilised during the booking process.
  • It is advisable to notify travellers about these variations.

Example of price discrepancy

Below are examples of two responses with minor price differences:

Here’s a sample response from the /accommodation/availability endpoint:

{
  "price": {
    "base": 8485200.18,
    "book": 9622217.00,
    "extra_charges": {
      "conditional": [],
      "excluded": [],
      "included": [
        {
          "charge": 1,
          "mode": "percentage",
          "percentage": 5.00,
          "total_amount": 424260.01,
          "unit_amount": null
        },
        {
          "charge": 21,
          "mode": "percentage",
          "percentage": 8.00,
          "total_amount": 712756.81,
          "unit_amount": null
        }
      ]
    },
    "total": 9622217.00
  }
}

In this case, the price discrepancy between the two endpoints is 0.20 cents.

Price
accommodation/availability
order/preview
Base price8485200.188485200.00
Total price9622217.009622216.80
Curious to know more?
  • Follow the Displaying pricing guide to learn how to present prices in your search results, availability and order pages.
  • See examples in best practices in the dedicated Pricing - use cases section.
  • For more information on setting up search and availability requests, explore the Search for accommodation section.
  • Refer to the Orders guide for examples and instructions on how to create an order.
Previous page
Next page