Cancellation policies
This guide outlines the cancellation policies supported by the Demand API and includes examples of how to retrieve policy details using various endpoints during both the pre-booking and booking phases..
Cancellation types
Cancellation policies play a crucial role in the booking process, determining the terms under which a traveller can cancel their reservation and whether they are entitled to a refund or must pay a fee.
There are three types of policies that are supported in Demand API:
Flexible policies - Free cancellation until
This policy allows travellers to cancel their bookings without incurring fees within a specified time frame, usually:
- 24-48 hours before checkin time.
- 7 days before arrival.
- By 12:00 PM on the day of arrival.
Properties can set how many days prior to the check in of the reservation the traveller can cancel for free.
This is ideal for travellers seeking flexibility in their plans.
Partially refundable policies - Special conditions
Bookings can be cancelled under this policy, but a cancellation fee may apply depending on how close the cancellation is to the checkin date.
Travellers will incur a cancellation fee based on a percentage of the total booking price.
- You can check the specific conditions and fees applied to products by reviewing the Preview Order response.
Properties can specify the terms of partial refunds.
Note that Third-party inventory accommodations do not offer special conditions policies on their products as only flexible and non-refundable policies are available.
Cancellation fees
There are 3 different fees that can be applied under special conditions:
- Check the cancellation fee calculation by looking at either the orders/details or orders/preview endpoints responses.
- Inform your travellers about the applicable fees during the booking process.
Non-refundable policies
Under this policy, travellers always have to pay the full amount of the total booking cost when cancelling.
- The charge may happen at any time from the booking.
- This policy is typically associated with lower-priced, non-flexible rates.
Do not forget to inform your travellers about this policy when displaying your product page and during the booking process.
Cancellation types/fees in Demand API
Our Demand API provides detailed information about the cancellation policies, timelines and fees for each product block.
Cancellation policies are returned per-product rather than per-order. This allows you to easily manage complex multi-room bookings where different policies apply to different rooms.
Similarly to what Booking.com offers in the website, each stage provides a different level of detail:
| Phase | Endpoint | Response |
|---|---|---|
| Pre-booking | accommodations/search accommodations/availability | Return basic information about the cancellation policy type. If free cancellation applies, you can check until when. Note: At this stage applicable special conditions fees are not yet disclosed. |
| Booking | orders/preview | Retrieve applied cancellation type together with timelines and applicable fees. |
| Post-Booking | orders/details/accommodations | Retrieve applied cancellation type together with timelines and applicable fees. |
Refer to the Try out guide for tips on how to use these endpoints.
Pre-booking
When searching for accommodations calling the /search and /availability endpoints, you can already get a simplified version of the cancellation policy.
The responses include a list of accommodations with products that meet the specified search criteria, together with the applied cancellation types.
Response key fields
These are the fields included in the response:
| Field | Description |
|---|---|
policies.cancellation | Provides all the details of the cancellation policy assigned to the product. |
free_cancellation_until | In case there is free cancellation, you can also see the date and time up to when an order for the product can be cancelled for free. If there is no free cancellation and special conditions or non-refundable policies apply, it returns “Null”. |
type | Cancellation scheme supported by the product. One out of the 3 available options: non_refundable, free_cancellation or special_conditions. |
The default timezone is UTC (Coordinated Universal Time) and the timestamps follow the ISO 8601 standard format.
Examples 1 - Free cancellation
On this request, for this property there is a flexible cancellation policy, and travellers can cancel for free until 2024-09-02T06:59:59+00:00.
"policies": { "cancellation": { "free_cancellation_until": "2024-09-02T06:59:59+00:00", "type": "free_cancellation" },
Inform your travellers on the available policies when displaying your product page.
Example 2 - Special conditions
In this case, the cancellation policy type is "special conditions" hence the free_cancellation_until field is marked as"null". This means there is no free cancellation and a fee may apply.
"products": [ }, "number_available_at_this_price": 10, "policies": { "cancellation": { "free_cancellation_until": null, "type": "special_conditions" }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "timings": [ "pay_at_the_property", "pay_online_later", "pay_online_now" ] } }, "price": { "book": 204.00, "total": 204.00 }, "room": 1050736002 },
At this stage fees are not yet disclosed for special conditions policies. Use the orders/preview endpoint to get further details on fees and timelines.
Example 3 - Non refundable policy
When a product has a "non_refundable" type of policy, the "free_cancellation_until" field returns null, as this is not applicable.
}, "products": [ { "id": "1000420_95127794_2_0_0", "children": [], "deal": null, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": null, "type": "non_refundable" }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "timings": [ "pay_at_the_property" ] }
At this stage fees are not yet disclosed for non-refundable policies. Use the orders/preview endpoint to get further details on fees and timelines.
Booking: Order/preview
To view the cancellation policy details for a specific product, call the orders/preview endpoint, and check the data.accommodation.products.policies.cancellation field.
Refer to the Create orders guide for tips and examples on using the orders/preview endpoint.
Response key fields
These are the fields included in the data.accommodation.products.policies.cancellation response:
| Field | Description |
|---|---|
From | This parameter indicates the time from which the cancellation fee applies. - Using now means the policy is effective immediately at the time of booking. |
Cancellation price | This field discloses the fee that must be paid upon cancellation. |
This endpoint provides a final review before the booking, so ensure that the cancellation policy details are clearly presented to travellers.
Example 1 - Free cancellation
In the following example:
"cancellation": [ { "from": "now", "price": { "accommodation_currency": 0.00, "booker_currency": 0.00 } }, { "from": "2024-11-02T07:00:00+00:00", "price": { "accommodation_currency": 279.00, "booker_currency": 279.00 }
from.now: Indicates that from the moment of the booking, the traveller must pay the indicated price (fee).- Here, the price is 0, reflecting a free cancellation policy.
The next
fromparameter specifies the deadline after which travellers will incur a cancellation fee (in this example 279.00)This indicates that travellers can cancel for free until 2024-11-02T06:59:59.
After this point, a cancellation fee will apply starting from 2024-11-02T07:00:00.
Example 2 - Non refundable
In the following example the from.now field indicates that from the moment of the booking, the traveller must pay the indicated fee for cancellations (170).
{ "id": "1000420_95127794_2_0_0", "policies": { "cancellation": [ { "from": "now", "price": { "accommodation_currency": 170, "booker_currency": null } }, "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 } }, "total": { "accommodation_currency": 195.06, "booker_currency": null }
Post-Booking: Orders/details
The Orders/details and Orders/details/accommodations endpoints present in their responses whether an order has been cancelled (in the status field) and also under which terms ( in cancellation_details field) including the cancellation fee that was charged, and when it was charged.
The cancellation_details field is null if the order has not been cancelled.
Best practices
When handling cancellation policies in your application:
- Clearly display cancellation terms to users during the booking process.
- When proceeding an order, it is crucial to emphasise the cancellation deadlines and fees within your application.
- For a better understanding of the cancellation process, check the Handling cancellations guide.
- Refer to the Orders section for instructions on how to use the orders/details and orders/preview endpoints.
- You can also check the workflow for pre-booking and booking phases in the Try out full guide.