# Handling order cancellations **This guide outlines the steps to cancel bookings for different travel services, including accommodations and car rentals.** ## The cancellation process Cancellations can occur for various reasons, such as booking errors or changes in travel plans. Before cancelling any order, ensure you understand the cancellation policies applicable to the specific travel service. * Always consult the [cancellation policies section](/demand/docs/orders-api/cancellation-policies) before proceeding with a cancellation. * Follow this guide step by step to streamline the cancellation process and avoid errors. ## Step-by-step process ![cancellation stepbystep](/assets/cancelstepbystep.4b78d3b65b490af53308b046d1a7d1884fec45b03caaf0baa10b0c92412a881e.5e2a7131.png) ### 1. Fetch the order/details Upon receiving a cancellation request, verify first the order ID and retrieve details for the travel service that needs to be cancelled. * Use /orders/details to get general order details. * Use /orders/details/accommodations or /orders/details/cars (orders/details/live if using 3.2 Beta) endpoints to check travel service specific details. **Example request** In your request, make sure you include the order IDs (or reservation IDs for cars). ```json { "orders": [ "121312354" ], "currency": "EUR", } ``` **Example response** The response includes information such as order status, payment method, price, and last update. ```json { "request_id": "01jrab3s38cr3k4wxmd6rsxx0m", "data": [ { "id": "121312354", "accommodations": { "reservation": 121312354 }, "affiliate": 956509, "booker": {...}, "cars": {...}, "created": "2026-02-04T10:24:59+00:00", "currency": "EUR", "flights": {...}, "payment": { "accommodations": { "authorisation_form": "https://secure-admin.booking.com/airplus_auth_form_pdf.html?token=anNvbl9hbXM0Xzg0ZmIyNWZhLTdmODAtNGRlZC04NTAxLWFiMDVhYmZhN2Q0OQ%3D%3D&lang=en-us", "receipt_url": null, "reservation": 121312354 }, "method": "card", "paid": null, "pending": null, "timing": "pay_at_the_property" }, "price": { "commissionable": 0, "total": 276.94 }, "status": "booked", "updated": "2026-02-04T10:25:00+00:00" } ] } ``` Refer to the [orders/details guidelines](/demand/docs/orders-api/order-details) for examples and best practices. ### 2. Verify the order status #### Accommodation statuses Accommodation orders can only be cancelled if their status is `booked`. Other statuses cannot be cancelled. ```json }, "status": "booked", "updated": "2026-02-04T10:25:00+00:00" } ``` These are the available statuses for accommodation orders: | Order status | Description | | --- | --- | | `booked` | Can be cancelled. | | `cancelled` | The order was automatically cancelled by the system. This can happen for operational or risk-related reasons, such as:* Suspected fraud. * Or when the guest’s payment card is flagged as invalid and not updated within the allowed time window (for example, 24 hours). | | `cancelled_by_accommodation` | The order was cancelled by the accommodation provider, for example due to availability issues or operational constraints. | | `cancelled_by_guest` | The order was cancelled by the guest, in accordance with the applicable cancellation policy. | | `stayed` | The stay has been completed and the guest has checked out. | | `no_show` | The guest did not arrive for the stay and the order was marked as a no-show by the accommodation, according to its no-show policy. | Multiroom statuses In cases where individual `products` have varying statuses, the "stayed" status takes precedence and is applied to both the accommodation and order status. For instance, if one room in the order is marked as "cancelled" while another is "stayed," the "stayed" status will be used for both the accommodation and the order. #### Car rental statuses | Order status | Description | | --- | --- | | `cancelled` | The order has been cancelled and is no longer active. | | `confirmed` | The booking is confirmed by the supplier and is active. | | `not_confirmed` | The order request exists but has not yet been confirmed by the supplier. | | `quote` | A price quote has been generated; the booking has not been placed. | | `completed` | The rental has finished and the order is fully completed. Cannot be cancelled. | | `processing` | The booking is being processed; payment or final confirmation is pending. | | `unknown` | The booking status is unknown or not available. | Important Only orders with the status “booked” for accommodation or "confirmed" for cars, can be cancelled. If you attempt to cancel an order with another status you will get an error message. Check the [error handling](/demand/docs/orders-api/cancel-order#handling-errors) section for more details. ### 3. Check the cancellation policy Before cancelling, verify eligibility for cancellation and any fees. * Evaluate deadlines, potential fees, and any conditions that could impact the cancellation process. * Help you communicate any penalties or refund policies to the traveller effectively. #### Example - orders/details/accommodation response: ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": "121312354", "accommodation": 123456, "accommodation_details": {...}, "accommodation_order_references": [ "12345", "ABED2312" ], "booker": {...}, "cancellation_details": { "at": "2026-04-02T00:00:00+00:00", "fee": { "accommodation_currency": 170.01, "booker_currency": 186.87 } }, "checkin": "2026-04-03", "checkout": "2026-04-08", "commission": {...} }, "credit_slip": 1223445, "currency": { "accommodation": "EUR", "booker": "USD" }, "key_collection_information": [...], "label": "One123", "pin_code": "1234", "price": {...}, "products": [ { "allocation": {...}, "guests": [...], "policies": { "cancellation": [ { "from": null, "price": { "accommodation_currency": 170.01, "booker_currency": 186.87 } } ], "price": { "base": { "accommodation_currency": 170.01, "booker_currency": 186.87 }, "total": { "accommodation_currency": 200.97, "booker_currency": 220.9 } }, "room": 12345, "room_details": {...}, "status": "booked" } ], "remarks": "We will need an extra cot. Need room on higher floor", "reservation": 123456, "status": "booked", "stay_probability": 0.12 } ] } ``` **What this data represents:** * The cancellation is free until 1 day before the checkin date (on the "2026-04-02T00:00:00+00:00") * From 2026-04-02 (UCT time) the traveller will be charged the fee (`186.87`) * At this point the order has not been cancelled yet, hence the status is "booked" and "cancellation.from" appears as "null". #### Example - orders/details/cars response (orders/details/cars/live in 3.2 Beta) Car rentals may have provider-specific rules. The response indicates the type of cancellation policy, schedules and fees: Note: Some car providers may not support fee waivers or special policies. ```json { "data": [ { "reservation": "11223344", "car": { "policies": { "cancellation": { "type": "free_cancellation", "schedule": [ { "from": "2026-10-14T10:00:00Z", "to": "2026-10-17T09:59:59Z", "free_cancellation": true, "price": null }, { "from": "2026-10-17T10:00:00Z", "to": "2026-10-19T10:00:00Z", "free_cancellation": false, "price": { "display": { "value": 25.00, "currency": "USD" }, "pay": { "value": 22.73, "currency": "EUR" } } } ] } } } } ] } ``` Always rely on the `schedule` — it provides the most accurate, time-sensitive cancellation logic, rather than just the high-level type. ### 4. Process the cancellation If the order meets the cancellation criteria, call the [cancellation order endpoint](/demand/docs/open-api/3.2/demand-api/orders/orders/cancel) to proceed. #### Required parameters When making a cancellation request either for accommodation or car rental, include the following required parameters: | Key parameters | | --- | | `reservation` | The unique identifier for the to-be cancel reservation. This value can be found in the [order/create](/demand/docs/open-api/3.2/demand-api/orders/orders/create) or [orders/details](/demand/docs/open-api/3.2/demand-api/orders/orders/details) response. | | `reason` | A description of the reason for cancellation, useful for tracking or reporting. Examples include: "Change in trip plans", "Wrong dates," or "Found another accommodation." | | `booker.country` | In case of car rental cancellations, the country is needed. | #### orders/cancel request examples **Accommodation cancellation request** ```json { "order": "509430129718799", "accommodation": { "reservation": "1234567890", "reason": "My travel dates have changed and I need to book a different property." } } ``` Optionally, you can use the `​request_property_approval` to `true` to request the accommodation to waive the fee and approve free cancellation. This is subject to accommodation approval though. See the [Cancel for less guide](/demand/docs/orders-api/3.2/cancel-for-less) for details. **Car rental cancellation** ```json { "car": { "reservation": "1234567890", "reason": "My travel plans have changed and I no longer need this car rental.", "booker": { "country": "es" } } } ``` #### Response status Upon a successful cancellation, the response confirm the operation. Example: ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "status": "successful" } } ``` If the cancellation fails it retrieves an error code and a failure status. Check the [Errors section](/demand/docs/orders-api/cancel-order#handling-errors) for more details. Important Please note that reservations may be automatically cancelled by our system if they are suspected to be fraudulent. ### 5. Review and confirm in order details After cancelling the order: * **Wait up to 1 hour** for the order to update. * Use the orders/details/accommodations and/or orders/details/cars (orders/details/cars/live if using v3.2 Beta) endpoints to verify the `status` value and the `cancellation details` again. At this stage, the status should be "cancelled" and in the `cancellation_details` you will be able to check: * The applied cancellation rules, including any fees and schedules. * The cancellation `fee` with the amount that must be charged for the cancellation, according to the applicable cancellation policy. In this example, the fee is 186.87 and must be paid at 2026-03-02T00:00:00+00:00: ```Json { "cancellation_details": { "at": "2026-03-02T00:00:00+00:00", "fee": { "accommodation_currency": 170.01, "booker_currency": 186.87 } } } ``` The `fee`is `null` if the cancelled product has a free cancellation policy. ### 6. Notify the traveller Send a confirmation notification including: * Status of the cancellation. * Any applicable fees or refunds. * Details on deadlines, if relevant. Example: ![cancellation-confirmation](/assets/confirmation2.46d9d64b8d40272ca838677ef32119573e2cf4a83417e4be3ca55363e58818db.5e2a7131.png) ## Handling errors If the cancellation is unsuccessful, the API returns an error message indicating the issue. Common error responses may include: | Error codes | | --- | | **403 Forbidden** | If you try to cancel an order immediately after it is created, you might receive a permission-denied message. Please wait a few minutes before attempting to cancel. | | **404 Not found** | The specified order ID does not exist. | | **409 Conflict** | The order cannot be cancelled due to its current state (e.g. stayed/completed). | | **500 server error** | Temporary server error. Wait a few minutes and try again. | | **504 Timeout** | Server unavailable or request took too long. Retry after a short delay (e.g., 30 seconds). | See the [general error handling guide](//demand/docs/support/error-handling/about-errors) for more details and examples. ### Examples of error responses **400 error messages:** * If you attempt to cancel an order with a “stayed” status, you will receive this error message, indicating that checkout has already occurred: ```json { "request_id": "01jc0echvzdvwt4g1vc0yj280f", "errors": [ { "id": "OrderNotCancellable", "message": "The order is no longer cancellable. Checkout was yyyy-mm-dd." } ] } ``` * A similar message will appear if the order was already cancelled: ```json { "request_id": "01jc0echvzdvwt4g1vc0yj280f", "errors": [ { "id": "OrderNotCancellable", "message": "The order has already been cancelled." } ] } ``` ## Important considerations * **User initiation**: Enable travellers to initiate the cancellation process through a user-friendly interface in your application. * Ensure they can easily access their booking information. * Keep the cancellation process simple and intuitive. Provide clear instructions and confirmation messages at each step. * **Cancellation policies**: Be aware of the cancellation policies linked to the order, as these will dictate whether a cancellation fee applies or if cancellation is possible without penalties. * Clearly communicate [cancellation policies](/demand/docs/orders-api/cancellation-policies) during the booking process to reduce confusion and enhance trust. * **Time sensitivity**: Some orders have specific time frames for cancellation. * Ensure you're acting within the allowed period to avoid complications. * Example: Cancellation cannot happen after checkin date. * **Testing and validation**: Rigorously test the cancellation feature to ensure it functions as intended across various scenarios, including edge cases. Curious to know more? * Refer to the [orders/details](/demand/docs/orders-api/order-details) guide for instructions and examples on how to use this endpoint. * Learn about the supported [cancellation policies](/demand/docs/orders-api/cancellation-policies) to provide the right information in the cancellation process.