Constructing cancellation policies
Understand how cancellation policies are modeled and exposed through the Rapid Lodging APIs
Overview
The Rapid Shopping API returns cancellation policy details for every rate in the Availability response. The specific cancellation policy for each rate is constructed from the below key objects:
- The tri-state flag
current_refundabilityprovides an accurate representation of the rate’s refundability at the time of making the request. - The
cancel_penaltiesobject defines policy windows with start/end dates, penalty types, and values. - The
nonrefundable_date_rangesdefines stay dates that will remain non-refundable for the booking (taking precedence overcancel_penalties).
Note: The ISO-8601 offset returned in cancel_penalties.start and cancel_penalties.end is the authoritative value to display and calculate against. This usually aligns to local property time, but may reflect supplier-configured timezone data and should not be recalculated from the property address/geography.
All examples on this page show the offset explicitly (for example, GMT+7:00) to reinforce that you should preserve and display it as given.
>> See specific policy display rules for California properties
Guidelines
Refundability
Use current_refundability as your primary control for refundability-driven logic and user experience; it is the most accurate representation of policy configuration, especially for partial-penalty scenarios.
| Value | Meaning |
|---|---|
refundable | Fully refundable |
non_refundable | No refund available |
partially_refundable | Penalty is more than 0 but less than the total booking value, and/or there are non-refundable date ranges within the stay |
The refundable boolean provides visibility over the policy’s refundability but is limited and does not fully describe how partial or complex penalties work, nor if other fees could apply. Any rate that is not fully refundable at time of booking will show refundable=false.
Non-refundable date ranges
Using the nonrefundable_date_ranges object to set stay dates that are non-refundable at time of booking is optional. Please note, the nonrefundable_date_range is inclusive of the nightly rate plus any taxes and fees.
Where a rate has non-refundable dates defined in the nonrefundable_date_ranges object these nights will be charged alongside any other cancellation penalty charges set out in the cancel_penalties object.
Property fees
When referencing fees payable in the event of cancellation, best practice is to use the terminology “property fee” instead of “cancellation fee” to reflect more accurately who collects the fee and why it is due.
Time of booking
The cancellation policy details will change in the response depending on whether the booking was made inside or outside of the cancellation penalty window. See the refundable property in the examples below.
Booking made inside the cancellation penalty window:
{
"itinerary_id": "9999999999999",
...
"rooms": [
{
"links": {
...
},
"id": "1111",
...
"status": "booked",
"checkin": "2026-08-03",
"checkout": "2026-08-07",
...
"rate": {
"id": "2222",
...
"refundable": false,
"cancel_refund": {
"amount": "0.00",
"currency": "USD"
},
"cancel_penalties": [
{
"currency": "USD",
"percent": "100%",
"start": "2026-07-16T06:56:59.311-07:00",
"end": "2026-08-03T23:59:00.000-07:00"
}
],
...
"pricing": {
...
}
}
}
]
}Booking made outside of the cancellation penalty window:
{
"itinerary_id": "9999999999999",
...
"rooms": [
{
"links": {
...
},
"id": "1111",
...
"status": "booked",
"checkin": "2026-09-27",
"checkout": "2026-10-02",
...
"rate": {
"id": "2222",
...
"refundable": true,
"cancel_refund": {
"amount": "-1131.85",
"currency": "EUR"
},
"cancel_penalties": [
{
"currency": "EUR",
"percent": "100%",
"start": "2026-07-18T01:21:30.000-07:00",
"end": "2026-09-27T23:59:00.000-07:00"
}
],
...
"pricing": {
...
}
}
}
]
}Policy components
The cancellation policy that you must present to travelers is derived from four major timeframes, plus a per-stay refund rule. All four timeframes should be considered in your logic and, when applicable, in your UI text.
Cancellation policy exception
Defined by: nonrefundable_date_ranges
These are stay dates that are completely non-refundable from the time of booking. If a booked night falls within one of these ranges, that night is always charged in full regardless of when the traveler cancels.
The date range is inclusive; the nightly rate plus any taxes and fees for the end date are also charged when the night is non-refundable.
If only part of the stay overlaps a non-refundable range, nights outside that range can still be refundable subject to the other penalty windows in cancel_penalties.
Traveler-facing messaging: These dates are non-refundable from booking; if you change or cancel your booking you will not get a refund or credit to use for a future stay for these days and will also need to pay any taxes and fees.
Free cancellation
This is the period between booking creation and the start of the earliest policy tier window with a penalty in the cancel_penalties object, excluding any nights that are in nonrefundable_date_ranges. Identify the earliest cancel_penalties.start across all windows and use that timestamp as the end of your free cancellation window.
Note: Cancellation policies can have up to 3 tier windows.
Traveler-facing messaging: Cancel your reservation before [start date time of the earliest penalty window], and you'll get a full refund. Any booked stay dates within a non-refundable date range will not be refunded.
Penalty cancellation
Defined by: Each element of cancel_penalties when present.
Supported penalty types
Within each penalty timeframe, nights in nonrefundable_date_ranges remain non-refundable and any additional penalties apply as configured in the applicable cancel_penalties window. Note, it is possible to combine amount + nights or amount + percent in the same timeframe, but not nights and percent together in a single tier window.
Amount penalty
- A fixed fee in a specified currency (e.g. 200 USD)
Traveler-facing messaging: If you cancel after [start date time of policy window] you'll be charged [amount] [currency].
Night penalty
- A charge for a specified number of nights plus taxes and fees (when multiple nights are booked, the charge is taken from the first night).
Traveler-facing messaging: If you cancel after [start date time of policy window] you'll be charged for [number of nights] night(s) plus taxes and fees.
Percent penalty
- A percentage of the total stay charges and fees (e.g. 90%).
Traveler-facing messaging: If you cancel after [start date time of policy window] you'll be charged [percentage] of your total stay.
Post-check-in cancellation and no-show
This is the period after the last configured penalty window (cancel_penalties[end]). In other words, the tier window just before the check-in time.
Traveler-facing messaging: If you no-show for this reservation, or if you cancel or change this reservation after check-in time, you'll be charged [amount/currency/number of nights/percentage as defined in the last configured penalty window].
Refunds for per-stay amounts
Per-stay amounts, returned in the stay object, follow a single rule:
- If any day of the stay is non-refundable, per-stay amounts are non-refundable
- Per-stay amounts are only refunded when the entire stay is fully refundable
Note: For VRBO properties, there are additional nuances around service fee charges and refunds – ask your Integration Consultant for more information.
Policy display updates for California properties
To comply with policy changes in California, the cancellation period must start exactly 24 hours after the booking creation timestamp, unless the booking is made within 72 hours of check-in. Expedia systems automatically adjust cancellation windows for any property located in California.
Expected behaviour examples:
- For a property located within California which has a rate that is fully refundable with no cancellation penalty in place, no changes will be made to the cancellation policy.
- For a property located within California that has a non-refundable rate with a cancellation penalty in place from the time of booking, the cancellation policy will be amended to start exactly 24 hours after the booking creation date.
- If a property is located outside of California, no changes will be made to the cancellation policy, even if the booking is made in California.
Pre-booking cancel policy
The updated cancel penalty window will automatically be displayed in the API call while the traveler is shopping. You may notice that the refundable flag remains false for non-refundable bookings and, as such, you will need to honor this based on the cancellation window. For hotels, that window is 24 hours from the booking timestamp. For Vrbo properties, it's until the end of the day following booking.
Post-booking cancel policy
After booking, the adjusted California policy continues to apply.
- Use
GET /itinerariesandcancel_refundfrom Manage Booking as your source of truth for whether a booking is refundable and how much should be returned. - Confirmation emails also show the adjusted cancel policy.
- The
refundableboolean in Shopping is not modified for this change; it continues to reflect whether a rate is intended to be non-refundable for filtering purposes. - The
refundableparameter in the Retrieve Itinerary response reflects whether the booking is currently within the applicable cancellation windows; use this to decide whether a booking is fully refundable when displaying post-booking options.