Cancellation Policies¶

Every package returned by search, quote and book carries a cancellationPolicy that tells you what cancelling the booking costs at any point in time. The same terms are then applied when you cancel the booking through the Bookings API.

There are two cancellation models:

Standard model¶

The policy is described by two fields:

Partial refundability¶

With partial refundability enabled, a package can carry a fee schedule in cancellationPolicy.fees:

Reading the schedule¶

• Cancellation is free before the first entry's since.
• Each entry applies from its since until the next entry's since. The last entry applies through check-in.
• amount is the absolute fee for the whole booking (all rooms and nights). The refund is the package total minus the fee in force at the moment you cancel.
• Fees never decrease over time. An entry whose amount equals the total price makes the booking non-refundable from its since.
• isRefundable: true together with fullRefundability: null means free cancellation has passed, but a partial refund is still available.
• fees is omitted (not an empty array) when the package has no fee schedule. Non-refundable packages carry no fees, and packages without a schedule are described by isRefundable and fullRefundability exactly as in the standard model. Always test for the key's presence.

Example¶

A package with a total price of 500.00 USD and check-in on 2026-12-10:

"cancellationPolicy": {
    "isRefundable": true,
    "fullRefundability": {
        "from": "2026-11-19T00:00:00Z",
        "to": "2026-12-01T12:00:00Z"
    },
    "fees": [
        { "since": "2026-12-01T12:00:00Z", "amount": 100.00 },
        { "since": "2026-12-06T12:00:00Z", "amount": 250.00 },
        { "since": "2026-12-09T12:00:00Z", "amount": 500.00 }
    ]
}

The same package requested on 2026-12-03, when the first fee is already in force:

"cancellationPolicy": {
    "isRefundable": true,
    "fullRefundability": null,
    "fees": [
        { "since": "2026-12-01T12:00:00Z", "amount": 100.00 },
        { "since": "2026-12-06T12:00:00Z", "amount": 250.00 },
        { "since": "2026-12-09T12:00:00Z", "amount": 500.00 }
    ]
}

Through the booking flow¶

Always show the end user the schedule returned by quote, not the one from search.

Cancelling a booking¶

Cancellation is requested with POST /api/bookings/{orderId}/cancel. The outcome depends on the fee in force at the moment the request is processed:

• After a successful cancellation the booking status becomes Cancelled, whether the refund was full or partial.
• The cancel response does not return the refunded amount. Calculate it from the booking's schedule, and reconcile the credit applied to your account through the Liabilities API.
• Refunds are credited in the booking's order-level currency.
• Cancellation is not available on the check-in date.

Schedule on existing bookings¶

GET /api/bookings/{orderId} and GET /api/bookings return the schedule of a booking as cancellationPolicies windows. A booking with a fee schedule returns one window per fee, preceded by the free-cancellation window when there is one:

For the example above, booked on 2026-11-20 with check-out on 2026-12-12:

"cancellationPolicies": [
    {
        "fee": 0,
        "availableFrom": "2026-11-19T00:00:00Z",
        "availableTo": "2026-12-01T12:00:00Z",
        "description": "Free cancellation",
        "refundability": "Refundable"
    },
    {
        "fee": 100.00,
        "availableFrom": "2026-12-01T12:00:00Z",
        "availableTo": "2026-12-06T12:00:00Z",
        "description": "Partial refund",
        "refundability": "Refundable"
    },
    {
        "fee": 250.00,
        "availableFrom": "2026-12-06T12:00:00Z",
        "availableTo": "2026-12-09T12:00:00Z",
        "description": "Partial refund",
        "refundability": "Refundable"
    },
    {
        "fee": 500.00,
        "availableFrom": "2026-12-09T12:00:00Z",
        "availableTo": "2026-12-13T00:00:00Z",
        "description": "Non-refundable",
        "refundability": "Refundable"
    }
]

Use fee to determine what cancelling within each window costs.