Handling cancellations

This guide outlines the steps necessary for a smooth cancellation experience, along with relevant examples.

Understanding the cancellation process

Cancellations can arise from various situations, including booking errors, or changes in travel plans. Therefore, it's crucial to familiarise yourself with the cancellation policies associated with each booking.

• Always consult the policies section before proceeding with a cancellation.

  Did you know?

  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.

• Make sure you understand the steps and recommendations provided in this guide to streamline your cancellation process.

Step-by-step process

1. Fetch the order/details/accommodations

Upon receiving a cancellation request, first verify the order ID and retrieve relevant booking details using the /orders/details/accommodations endpoint.

Follow the orders/details guidelines for examples and tips on how to use it.

Example of Orders/details response:

{
  "id": "xxxxxxxxxxxxx",
  "accommodation": "xxxxxxx",
  "accommodation_details": {
    // Add relevant details here
  },
  "accommodation_order_references": [],
  "cancellation_details": null,
  "checkin": "2025-08-24",
  "checkout": "2025-08-26",
  "commission": {
    // Add relevant details here
  },
  "price": {
    "commissionable": {
      "accommodation_currency": 170.01,
      "booker_currency": 147.40
    },
    "total": {
      "accommodation_currency": 180.01,
      "booker_currency": 153.40
    }
  },
  "products": [
    {
      // Add relevant product details here
    }
  ],
  "policies": {
    "cancellation": [
      {
        "from": "2025-08-22T14:22:43+00:00",
        "price": {
          "accommodation_currency": 45.00,
          "booker_currency": 38.35
        }
      }
    ]
  },
  "status": "booked",
  "updated": "2024-11-07T13:42:13+00:00"
}

Verify the order status

Check the status of the order and last update.

In the example provided: the order has a booked status, and was last updated on the "2024-11-07T13:42:13+00:00" (UTC time)

The following statuses indicate that an order cannot be cancelled:

• "cancelled"
• "cancelled_by_accommodation"
• "cancelled_by_guest"
• "stayed"

If you attempt to cancel an order with a “stayed” or "cancelled" status you will receive a 400 error message. Check the error handling section for more details.

Multi-room 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.

Check the cancellation policy

Before proceeding, verify the booking's eligibility for cancellation according to its specific terms.

Evaluate deadlines, potential fees, and any conditions that could impact the cancellation process. This will help you communicate any penalties or refund policies to the traveller effectively. For the sample order provided:

{
  "policies": {
    "cancellation": [
      {
        "from": "2025-08-22T14:22:43+00:00",
        "price": {
          "accommodation_currency": 45.00,
          "booker_currency": 38.35
        }
      }
    ]
  }
}

• The cancellation is free until 2 days before the checkin date.
• From 2025-08-22 (UCT time) the traveller will be charged the stated amount (38.35)

2. Process the cancellation

The API provides a dedicated endpoint for cancelling orders, ensuring compliance with the booking's cancellation policies. If the order meets the cancellation criteria, call the cancellation order endpoint to proceed.

Required parameters

When making a cancellation request, include the following parameters:

• order_id: The unique identifier for the order you wish to cancel. This value can be found in the order/create or orders/details response.
• cancellation_reason (optional): A description of the reason for cancellation, useful for tracking or reporting. Examples include: "Change in trip plans," "Wrong dates," or "Found another accommodation."

Request example:

{
  "order": "509430129718799",
  "reason": "Change in trip plans."
}

Response status

When using the cancellation endpoint to cancel an order, you may receive the following response statuses:

• Successful
• Failed

Upon successful cancellation, the response will confirm the operation. Example:

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "status": "successful"
  }
}

If the cancellation fails it retrieves an error code and message. Check the handling errors section for more details.

3. Review and confirm in order details

After cancelling the order, use the orders/details/accommodations endpoint to verify the status value and cancellation details.

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 timelines.
• The cancellation fee should indicate the amount that must be charged for the cancellation, according to the applicable cancellation policy.

In this example, the fee is 186.87 that must be paid at 2024-11-09T00:00:00+00:00:

{
  "cancellation_details": {
    "at": "2024-11-09T00:00:00+00:00",
    "fee": {
      "accommodation_currency": 170.01,
      "booker_currency": 186.87
    }
  }
}

The fee field is null if the cancelled product has a free cancellation policy.

4. Notify the traveller

After successfully cancelling the booking, send a confirmation notification to the traveller.

Include details about the cancellation and any applicable refunds. Example:

Always confirm the cancellation status with the guest to ensure they are informed.

Handling errors

If the cancellation is unsuccessful, the API returns an error message indicating the issue.

Common error responses may include:

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:

{
  "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:

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