Cancel for less v3.2

Enable travellers to request an accommodation cancellation without paying the usual fee if the property approves.

The cancellation process

The Cancel for less flow allows partners to request the property to waive the cancellation fee for a reservation.

• This is useful when travellers want to cancel an existing booking due to an urgent matter.
• This flow is only applicable when the cancellation has a fee.

Overview

• The request is made through the v3.2 orders/cancel endpoint.
• The property must approve the request for it to be effective.
• This functionality is activated by a flag in the request.
• Not all properties accept free cancellation requests. Partners can check this at the property level using accommodations/details.

Step-by-step process

1. Check Cancel for less eligibility

To determine whether a property allows waiving cancellation fees, include extras.refuses_free_cancellation_requests in the accommodations/details request.

Example of request:

{
    "extras": ["refuses_free_cancellation_requests"]
}

The response will retrieve whether this is allowed by the property.

{
    "data": [
        {
            "refuses_free_cancellation_requests": false
        }
    ]
}

• true → Property will not accept requests to cancel for free.
• false → Property may approve a free cancellation request.

2. Send cancellation request

If the property accepts this sort of requests, you can send a cancellation request via the orders/cancel endpoint.

• Include the request_property_approval flag set to "true" in your orders/cancel request.
• When set to true, in case the reservation has a cancellation fee, it requests the property to waive the fee. Subject to approval.

Example:

{
    "order": "509430129718799",
    "reason": "I would like to book another property instead of this one.",
    "request_property_approval": true
}

3. Check applied cancellation fee

Check orders/details to verify at a reservation level whether the booking has included the cancellation fee or not.

• You can check the order status and verify it has a "Cancelled_by_guest" status.

Handling errors

Common error responses may include:

Cancellation request not approved

Issue: The property does not approve the free cancellation request.

Solution:

• Confirm the property allows free cancellation requests using accommodations/details and the refuses_free_cancellation_requests field.
• If refuses_free_cancellation_requests is true, the property will not accept the request.
• Encourage travellers to contact the property directly if urgent.

Attempting to cancel an ineligible order

Issue: You receive a 400 error when calling orders/cancel.

Solution:

• Only orders with status set to booked can be cancelled.
• Verify the order status using orders/details before attempting cancellation.

Incorrect request payload

Issue: Cancellation request fails due to missing or incorrect fields.

Solution:

• Ensure request_property_approval is included and set to true.
• Include a valid order ID and a meaningful reason for cancellation.

Example of correct payload:

{
    "order": "509430129718799",
    "reason": "I would like to book another property instead of this one.",
    "request_property_approval": true
}

Property information not available

Issue: refuses_free_cancellation_requests is missing in the response.

Solution:

• Include "extras": ["refuses_free_cancellation_requests"] in your v3.2 accommodations/details request.
• Ensure the request is targeting the correct property ID and using Demand v3.2 endpoints.
• If still unavailable, the property may not support free cancellation requests via the API.

Delayed approval from the property

Issue: Response indicates request is pending.

Solution:

• Approval depends on the property. Some may take time to respond.
• Use orders/details periodically to check the current approval status.
• Notify the traveller that the cancellation is under review.

Best Practices for implementation

✓ Always check property cancellation policy first - Prevent unnecessary requests to properties that refuse free cancellations.

✓ Provide a clear reason - The reason field improves approval chances and helps the property understand the context.

✓ Handle approvals asynchronously - Approval is not guaranteed and may take time; inform travellers accordingly.

✓ Integrate with orders/details - Confirm at the reservation level whether the booking allows a free cancellation request.

✓ Testing and validation - Rigorously test the cancellation feature to ensure it functions as intended across various scenarios, including edge cases.