Locate the cancellation policy object in the rate/offer response — field names vary by API (e.g. cancellationPolicies[], policies.cancellations[], cancel_penalties[]); always read API-specific docs for structure.
Parse each policy rule: extract the deadline (ISO 8601 datetime), the penalty_amount or penalty_percentage, and the currency; convert the deadline to UTC for internal logic and to hotel-local time for user display.
A 'free cancellation until' date means the guest can cancel with no charge before that datetime — after the deadline, the penalty applies; model this as a sorted list of deadline/penalty pairs.
Guarantee means the hotel will hold the room but charge the card only at check-in (or no-show/late cancel); deposit means a partial or full charge is taken immediately at booking — check the rate's guarantee_type or deposit_policy fields.
For non-refundable rates, the full amount may be charged at booking — confirm this with a user-facing warning before completing the order; do not treat non-refundable the same as a penalized cancellation.
Store the raw policy string alongside your parsed version — hotels sometimes update policies and your parsed snapshot is the legally relevant one at time of booking.
Known gotchas
Cancellation deadlines in hotel APIs are often expressed in the hotel's local timezone without explicit offset — a deadline of '2026-08-15T23:59:00' for a Tokyo hotel means Japan Standard Time (UTC+9), not UTC; always resolve timezone before storing.
Some APIs return a 'fully refundable' flag that is computed from the policy rules — this flag can be wrong if the rules parsing logic has edge cases; always validate against the raw deadline/penalty array.
Guarantee policies can silently become deposit policies if the check-in date is within a short window (e.g. 24 hours); re-read the policy immediately before booking if there is any delay between rate display and order creation.
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