This guide outlines the cancellation policies supported by Demand API and includes examples of how to retrieve policy details using various endpoints during the pre-booking, booking and post-booking phases.
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 with different level of flexibility:
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.
Bookings can be cancelled under this policy, but a cancellation fee will always apply.
- Travellers will incur a cancellation fee based on 50% of the total booking price or the cost of the first night stay.
- Properties decide the terms of the partial fees and refunds.
- You can check the specific conditions and fees applied to products by reviewing the order/preview response.
Note that Third-party inventory accommodations do not offer special conditions policies on their products as only flexible policies are available.
Under this policy, travellers must always pay the full amount of the total booking cost when cancelling their bookings, unless local laws specify otherwise.
- The charge may happen at any time from the booking.
- This policy is typically associated with lower-priced, non-flexible rates.
There are 3 different fees that can be applied:
- 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.
✓ Do not forget to inform your travellers about the applicable policy when displaying your product page and during the booking process.
✓ Make sure you display the cancellation fee in line to local regulation. Example: Properties in Germany cannot charge 100% of total booking cost for cancellations by law.
Our Demand API provides detailed information about the cancellation policies, schedules and fees for each product block.
Cancellation policies are returned per-product rather than per-order. This allows you to easily manage complex multi-product (rooms, cars, etc) bookings where different policies apply to different selected products.
Similarly to what Booking.com offers in the website, each stage provides a different level of detail:
| Phase | Endpoint | Response |
|---|---|---|
| Pre-booking |
| 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 endpoint | Retrieve applied cancellation policy type together with schedules and applicable fees. |
| Post-booking | orders/details/* endpoints | Returns the cancellation details per product (room or car selected) including the applicable type of policy together with schedules and fees. |
The default timezone in our Demand API is UTC (Coordinated Universal Time) and the timestamps follow the ISO 8601 standard format.
When searching for accommodations calling the accommodations/search and /availability endpoints, you can retrieve a simplified version of the cancellation policy.
| 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 partially refundable or non-refundable policies apply, it returns “Null”. |
type | Cancellation policy applicable to the product.
|
The default timezone in our Demand API is UTC (Coordinated Universal Time) and the timestamps follow the ISO 8601 standard format.
On this request, for this property there is a flexible cancellation policy, and travellers can cancel for free until 2025-10-06T21:59:59+00:00
"policies": {
"cancellation": {
"free_cancellation_until": "2025-10-06T21:59:59+00:00",
"schedule": [
{
"from": "now",
"price": 0
},
{
"from": "2025-10-06T22:00:00+00:00",
"price": 4716.9
}
],
"type": "free_cancellation"
}
}In this case, the cancellation policy type is "partially_refundable (or special_conditions in v3.1) 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 schedules.
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"
]
}
}
}
]
}
When searching for cars calling the /search and /availability (3.2 Beta) endpoints, you can check a simplified version of the cancellation policy.
These are the fields included in the response:
| Field | Description |
|---|---|
policies.cancellation | Provides all the details of the cancellation policy assigned to the product. |
type | Cancellation policy applicable to the product. One out of the 2 available options: non_refundable, free_cancellation. |
details |
|
On this request, for this car there is a flexible cancellation policy, and travellers can cancel for free up to 48 hrs before pick up.
"policies": {
"cancellation": {
"type": "free_cancellation",
"details": {
"context": "before_pickup",
"duration": "PT48H"
}
},For non_refundable cancellation policies:
"policies": {
"cancellation": {
"type": "non_refundable",
"details": {
"context": "null",
"duration": "null"
}
},
Car rentals do not support "special conditions" or "partially_refundable".
To view the cancellation policy details and final fees for a specific product use the orders/preview endpoint.
Check either the:
data.accommodation.products[].policies.cancellation- for accommodation product cancellation policies-related details.data.car.policies.cancellation- for car cancellation policies-related details.
Refer to the Create orders guide for examples.
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. |
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.
In the following example:
"products": [
{
"id": "1000420_278556531_2_0_0",
"deal": null,
"policies": {
"cancellation": [
{
"from": "now",
"price": {
"accommodation_currency": 0,
"booker_currency": null
}
},
{
"from": "2025-12-08T23:00:00+00:00",
"price": {
"accommodation_currency": 177.65,
"booker_currency": null
}
}
]
}
}
]from.now- Indicates that from the moment of the booking, the traveller must pay the indicated price.- Here, the
price.accommodation_currencyis 0, reflecting a free cancellation policy.
- Here, the
The
fromdate specifies the deadline after which travellers will incur a cancellation fee (in this example 177.65)- This indicates that travellers can cancel for free until 2025-12-08T23:00:00+00:00.
- After this point, the indicated cancellation fee applies.
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
}
}
}The orders/details/* 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.
In this example the cancellation_details field is null because the order has not yet been cancelled, and the checkin is on the "2026-08-24".
{
"accommodation_order_references": [],
"cancellation_details": null,
"checkin": "2026-08-24",
"checkout": "2026-08-26",
"commission": {...},
"products": [
"policies": {
"cancellation": [
{
"from": "2026-08-22T14:22:43+00:00",
"price": {
"accommodation_currency": 45.00,
"booker_currency": 38.35
}
}
]
},
"status": "booked"
}
- The cancellation is free until 2 days before the checkin date.
- From 2026-08-22 (UCT time) the traveller will be charged the stated amount (38.35)
In this example, there is a fee applied to the cancellation.
{
"request_id": "01fr9ez700exycb98w90w5r9sh",
"data": [
{
"id": "509430129718799",
"reservation": "12345678",
"status": "cancelled",
"checkin": "2025-12-10",
"checkout": "2025-12-18",
"cancellation_details": {
"at": "2025-12-09T00:00:00+00:00",
"fee": {
"accommodation_currency": 170.01,
"booker_currency": 186.87
},
"original_total_price": {
"accommodation_currency": 170.01,
"booker_currency": 186.87
}
}
}
]
}When using the orders/details/cars/live in Beta version (future orders/details/cars in v3.3)
{
"cancellation": {
"type": "free_cancellation",
"schedule": [
{
"from": "2025-10-14T10:00:00Z",
"to": "2025-10-17T09:59:59Z",
"free_cancellation": true,
"price": null
},
{
"from": "2025-10-17T10:00:00Z",
"to": "2025-10-19T10:00:00Z",
"free_cancellation": false,
"price": {
"display": {
"value": 25.00,
"currency": "USD"
},
"pay": {
"value": 22.73,
"currency": "EUR",
"timing": "pay_online_now"
}
}
}
]
}
}Key parameters:
free_cancellation→ boolean indicating whether any free cancellation window exists.schedule→ chronological array of cancellation windows.
Each window contains:
from→ start datetime for that fee.price→ object with booker_currency and supplier_currency.
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.