# Cancellation policies

**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 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 with different level of flexibility:

![cancellation-policies](/assets/cancellationpolicies.329b7db045f4ce528009f1f653baa3d32268ba846850364ed45decb29d53ceb1.5e2a7131.png)

### 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.

### Special conditions policies (Partially refundable in v3.2 )

Bookings can be cancelled under this policy, but a cancellation fee will always apply.

* Travellers will incur a [cancellation fee](/demand/docs/orders-api/cancellation-policies#cancellation-fees) 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.


![partially-refund](/assets/partially-refundable.4643edec0509d3bf1ba3afe687deca24a078b1aaf19902431b847ce4a27d420b.5e2a7131.png)

* You can check the specific conditions and fees applied to products by reviewing the [order/preview](/demand/docs/open-api/demand-api/orders/orders/preview) response.


Note that [Third-party inventory](/demand/docs/accommodations/tpi/search-book-tpi-rates#cancel-a-tpi-booking#cancellation-restrictions) accommodations do not offer special conditions policies on their products as only flexible policies are available.

### Non-refundable policies

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.


![non-refund](/assets/non-refundable.8721aeea074f2e3a684fcf55d98c823fbf02f177df528b8d7c1959b15ec46bd5.5e2a7131.png)

## Cancellation fees

There are 3 different fees that can be applied:

![policies](/assets/policies.d2c4bf3e9ff1c0a05127cc4471b0da844b1da41a28063a6c14d7e4f19fb65d05.5e2a7131.png)

- Check the cancellation fee calculation by looking at either the [orders/details](/demand/docs/open-api/demand-api/orders/orders/details) or [orders/preview](/demand/docs/open-api/demand-api/orders/orders/preview) endpoints responses.
- Inform your travellers about the applicable fees during the booking process.


### Important considerations

✓ 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.

## Cancellation types/fees in Demand API

Our Demand API provides detailed information about the cancellation policies, schedules and fees for each product block.

Multi-product policies
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** | * /search
* /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 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. |


Timezone and timestamp
The default timezone in our Demand API is UTC (Coordinated Universal Time) and the timestamps follow the ISO 8601
standard format.

## Pre-booking - Search and availability

### Accommodation examples

When searching for accommodations calling the accommodations/search and /availability endpoints, you can retrieve a simplified version of the cancellation policy.

#### Response key fields

| **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.* One out of the 3 available options: `non_refundable`, `free_cancellation` or `partially_refundable` (`special_conditions` in v3.1).

 |


Timezone and timestamp
The default timezone in our Demand API is UTC (Coordinated Universal Time) and the timestamps follow the ISO 8601
standard format.

#### Example 1 - Free cancellation until

On this request, for this property there is a [flexible cancellation policy](/demand/docs/orders-api/cancellation-policies#flexible-policies---free-cancellation-until), and travellers can cancel for free until 2025-10-06T21:59:59+00:00

v3.1 response

```json

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

v3.2 response

```json

"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": {
            "accommodation_currency": 4716.9,
            "booker_currency": 4716.9
      }
    ],
    "type": "free_cancellation"
  }
}
```

#### Example 2 - Partially refundable (special conditions)

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.


```json
"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.

#### 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.


```json
{
  "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"
          ]
        }
      }
    }
  ]
}
```

### Car rental examples

When searching for cars calling the [/search](/demand/docs/open-api/3.2/demand-api/cars/search) and [/availability](/demand/docs/open-api/3.2-beta/demand-api/cars/availability) (3.2 Beta) endpoints, you can check a simplified version of the cancellation policy.

#### 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. |
| `type` | Cancellation policy applicable to the product. One out of the 2 available options: `non_refundable`, `free_cancellation`. |
| `details` | * `context`- The context in which the cancellation policy applies. For example 'before_pickup'
* `duration`- The duration until which the cancellation is free. This is in [ISO-8601/Duration format](/demand/docs/development-guide/code-conventions#durations).

 |


#### Example 1 - Free cancellation

On this request, for this car there is a [flexible cancellation policy](/demand/docs/orders-api/cancellation-policies#flexible-policies---free-cancellation-until), and travellers **can cancel for free up to 48 hrs before pick up**.


```json

"policies": {
      "cancellation": {
        "type": "free_cancellation",
        "details": {
          "context": "before_pickup",
          "duration": "PT48H"
        }
      },
```

#### Example 2 - No refundable

For non_refundable cancellation policies:


```json
"policies": {
      "cancellation": {
        "type": "non_refundable",
        "details": {
          "context": "null",
          "duration": "null"
        }
      },
```

Car rentals do not support "special conditions" or "partially_refundable".

## Booking - Orders/preview

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](/demand/docs/orders-api/order-preview-create#/orders/preview) for examples.

### Accommodation examples

#### 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. |
| `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 until

In the following example:


```json
"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_currency` is 0, reflecting a free cancellation policy.
* The `from` date 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.


#### 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).


```json
{
  "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/* 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.

### Accommodation examples

#### Example - Free cancellation until

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".


```json
{
  "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)


#### Example of cancelled order with fee

In this example, there is a fee applied to the cancellation.


```json
{
  "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
        }
      }
    }
  ]
}
```

### Car rental examples

When using the [orders/details/cars/live](/demand/docs/open-api/3.2-beta/demand-api/orders/details/cars/live) in Beta version (future orders/details/cars in v3.3)


```json
{
  "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.


## 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.


Curious to know more?
* For a better understanding of the cancellation process, check the [Handling cancellations](/demand/docs/orders-api/cancel-order) guide.
* Refer to the [Orders section](/demand/docs/orders-api/overview) 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](/demand/docs/getting-started/try-out-the-api).