During the shopping response, extract the cancel_penalties array from each rate option; each entry contains start (ISO 8601 datetime), end (ISO 8601 datetime), penalty_type (e.g., NIGHTS, AMOUNT, PERCENT), and value.
Convert the start and end timestamps to the property's local time using the property_timezone field in the rate response — cancellation deadlines are enforced in property local time, not the customer's timezone.
At cancellation request time, compare the current UTC timestamp to the penalty window boundaries; if the current time is before the first penalty window's start, the cancellation is penalty-free.
If within a penalty window, compute the penalty amount: NIGHTS type multiplies by the nightly rate, PERCENT type multiplies by the total stay cost, and AMOUNT type is a fixed charge; surface this to the user before confirming cancellation.
Display the cancellation policy in the booking confirmation using human-readable rendering of the penalty windows: 'Free cancellation until [local date/time at property]; after that, a [X] night penalty applies.'
After cancellation, store the penalty_amount charged and refund_amount returned from the cancel API response; these override the pre-calculated estimate if the property has applied a different rate at time of cancellation.
Known gotchas
The nonrefundable_date_ranges object in Rapid responses is separate from cancel_penalties and represents blackout periods (e.g., holidays) when the rate is fully non-refundable regardless of when the cancellation occurs — process both objects together.
For California-booked properties, the Rapid API enforces a mandatory 24-hour free-cancellation period from booking creation time by law — the penalty window start is adjusted automatically; do not override this in your cancellation UI.
Some rates have overlapping penalty windows (e.g., 50% penalty up to 3 days before, then 100% within 3 days) — iterate through the entire array and apply the first matching window at cancellation time.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp