# Accommodation pricing guide **Understand how accommodation pricing works across endpoints, how to interpret different price components, and how to display prices accurately and transparently in your platform.** ## Overview This guide explains the accommodation pricing model used in Demand API. It is structured to help you: * Understand price components. * Retrieve price data correctly from different endpoints. * Display price information clearly and lawfully. See the [Extra charges guide](/demand/docs/accommodations/charge-calculation) for charges calculation and examples. ## Key pricing concepts 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: * Displays the price breakdown with different fields and their values. * Defines *what* the traveller will or might have to pay. However, you cannot find here *when* or *how* the traveller must pay, for this information see the [Payments section](/demand/docs/payments/overview). Before diving into endpoints, let’s clarify the pricing model and key price fields. ### Price object fields | Field | Description | Usage | | --- | --- | --- | | `base` | The core cost of a booking before any included or extra charges are added. | | `book` | The display price that must be shown to the traveller under local booker protection laws. * This price includes the base accommodation cost (`base` price) and all charges that are legally required to be part of the displayed price (`included` extra charges). | **Use the `book` price when showing prices and availability to travellers before booking.** | | `total` | The full cost the traveller is expected to pay, either through Booking.com or directly to the accommodation provider. * Includes `book` price + `excluded` and `non_conditional` `extra_charges`. | **Use the total price to show the full amount payable when booking, regardless of payment method**. | | `extra_charges` | Additional costs that are applied to the base price. | See the [Extra charges guide](/demand/docs/accommodations/charge-calculation) for details. | | `chargeable_online` | The portion of the `total` amount that Booking.com charges online, if using Booking's payment system. * This amount is always less than or equal to the `total` price. | Use `chargeble_online`: * **When calculating the online charge collected via Booking.com** * **To know how much you need to load on your Virtual Credit Card (VCC)**. | See the [Usage best practices](/demand/docs/accommodations/prices-best-practices) for more details. ### Pricing comparison across endpoints There are slightly different parameters in the accommodations/search and availability responses, and those offered in orders/preview response. | Field | /accommodations/search and /availability | /orders/preview | | --- | --- | --- | | `base` | ✓ | ✓ | | `book` | ✓ | ✗ Not returned | | `extra_charges` | `included`, `excluded`, `conditional` | `non_conditional`, `conditional` | | `total` | ✓ | ✓ | | `chargeable_online` | ✗ | ✓ | ## Retrieving price information Use the following endpoints to access accommodation pricing information: | Endpoint | Use it to... | Best practice | | --- | --- | --- | | /accommodations/search /accommodations/availability | Show upfront pricing, eligibility-based rates/deals. | In the request: include `products` and `extra_charges` in the `extras` field. | | /orders/preview | Before finalising the booking, review the detailed pricing information to ensure they are correct. | Display all `non_conditional` charges to your traveller before payment. | Refer to the [Search and availability ](/demand/docs/accommodations/search-for-available-properties#optional-fields), and [Orders](/demand/docs/orders-api/order-preview-create) guides for specific instructions on how to make requests to these endoints so all extra charges are returned in the responses. ### Example accommodations/availability response Here's an example of an [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) response, with the `price` object breakdown, including `extra_charges`: ```json { ... "currency": "GBP", "products": [ { "id": "xxxxxxxxx_xxxxxxxxx_x_x_x", "price": { "base": 153.40, "book": 167.21, "extra_charges": { "conditional": [...], "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: `Base`, `book` and `total` price, as well as `conditional`, `excluded` and `included` extra charges. Find the full explanation in the [Pricing use cases section](/demand/docs/accommodations/pricing-examples). ### Example orders/preview response The pricing breakdown returned by the [/orders/preview endpoint](/demand/docs/open-api/demand-api/orders/orders/preview) includes the `base` and `total` prices, and also the `chargeable_online` field. ```json "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`](/demand/docs/accommodations/prices-accommodations#non-conditional-charges) additional charges indicate the final charges that have been included in the total price and must be paid to proceeed the booking. * `chargeable_online: 100` means that 100 out of 123 of the total price, will be charged by Booking online. See the specific [Chargeable online use case](/demand/docs/accommodations/pricing-examples#chargeable-online) for more details. Prices returned in API responses may differ slightly across endpoints due to rounding, country-based rules, rate availability, and inventory timing. ## Currency and rounding considerations All amounts are displayed in both the `accommodation_currency` and the `booker_currency`. * Small discrepancies may appear due to currency conversion or rounding logic. * To prevent errors due to rounding: * Authorise a small buffer (e.g. a few cents) during initial payment authorisation. * Use consistent rounding rules across all steps. 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: ```json "total": { "accommodation_currency": 92.00, "booker_currency": 78.95 } ``` * 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. ## Handling price discrepancies Price values between accommodations/availability and /orders/preview responses may differ slightly due to: * **Inventory changes** – Availability and pricing may fluctuate in real time as rooms are booked or released. * **Rate restrictions** – Some rates are only available under specific conditions, such as non-refundable policies or minimum stay requirements. * **Country-based pricing** – Prices may vary depending on the country of the booker, and regulatory requirements. * Example: Some countries display prices inclusive of all taxes and fees, while others show a breakdown of base price and additional fees. * **Guest or date modifications** – When changing the number of guests or reservation dates (using the /orders/modify endpoint) may result in a different `total` price. If prices differ: * Always rely on /orders/preview for the final, chargeable amount. * Notify travellers about these variations. ### Example of price discrepancy Below are examples of two responses with minor price differences: accommodations/availability price Here’s a sample response from the [/accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) endpoint: ```json { "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 } } ``` preview/order price And for the same request, the [preview/order endpoint](/demand/docs/open-api/demand-api/orders/orders/preview) response shows the following pricing: ```json { "price": { "base": { "accommodation_currency": 8485200.00, "booker_currency": null }, "extra_charges": { "conditional": [], "non_conditional": [ { "charge": 1, "mode": "percentage", "percentage": 5.00, "total_amount": { "accommodation_currency": 424260.00, "booker_currency": null }, "unit_amount": { "accommodation_currency": null, "booker_currency": null } }, { "charge": 21, "mode": "percentage", "percentage": 8.00, "total_amount": { "accommodation_currency": 712756.80, "booker_currency": null }, "unit_amount": { "accommodation_currency": null, "booker_currency": null } } ] }, "total": { "accommodation_currency": 9622216.80, "booker_currency": null } } } ``` In this case, the price discrepancy between the two endpoints is **0.20** cents. | Price | accommodations/availability | order/preview | | --- | --- | --- | | Base price | 8485200.18 | 8485200.00 | | Total price | 9622217.00 | 9622216.80 | ### How to handle price discrepancies When you notice slight price differences between the /accommodations/availability and /orders/preview endpoints, we recommend: Recommendation * **Trust /orders/preview for final pricing** * This endpoint reflects the most accurate and chargeable price after applying all relevant rules, such as guest count, stay duration, and regional pricing requirements. * It should be your single source of truth when confirming an order. * **Show price as “estimated” during the selection flow** * If you display prices from /accommodations/availability, label them as estimated or starting from. * This sets the right expectation for travellers and accommodates any minor variations later in the flow. * **Use /orders/preview to validate before placing an order** * Before confirming a booking with /orders, send a final check via /orders/preview using the same parameters. * This helps avoid surprises or failed orders due to price mismatches. * **Explain the discrepancy to users (if relevant)** * If travellers notice a small price change, consider showing a brief explanation such as: > “Final price may vary slightly due to taxes, currency rounding, or policy conditions.” * **Store prices for short durations only** * Avoid storing or caching availability prices for too long. Inventory and pricing can change quickly, and using stale data may lead to mismatches. * **Flag significant differences** * If you detect a large discrepancy (beyond expected rounding), log or alert your system to investigate further. * This may indicate a configuration issue or regional pricing rule in effect. ## Next steps For best practices and full details on how charges are calculated or displayed, see: * [Pricing best practices](/demand/docs/accommodations/prices-best-practices) * [Extra charges calculation](/demand/docs/accommodations/charge-calculation) * [Displaying prices](/demand/docs/accommodations/display-prices) * [Pricing and charges use cases](/demand/docs/accommodations/pricing-examples)