What is a hotel cancellation policy in a booking API?

It is the set of rules that says how much a guest pays if they cancel a reservation at a given moment. Suppliers express it as deadlines and penalties, for example free until a certain date and time, then one night or the full stay. A booking platform has to read that policy, store it with the booking and apply it on cancellation.

Why do cancellation deadlines cause so many disputes?

Because the deadline is often ambiguous: it may be in the hotel’s local time, the supplier’s time or UTC, and it may be shown to the customer rounded or converted incorrectly. If the platform shows a later deadline than the supplier enforces, the platform usually absorbs the penalty.

Should a platform add a buffer to supplier cancellation deadlines?

Many platforms do. Showing the customer a deadline slightly earlier than the supplier’s gives time to process the cancellation with the supplier before the penalty applies. The size of the buffer is a business decision and should be configurable.

Hotel cancellation policies: modelling refundability correctly in a booking platform

A hotel cancellation policy tells you what a guest owes if they cancel at a given moment. Every hotel supplier — a bedbank, a channel manager, a chain’s direct API — returns one with each rate, but they express it differently, and most of the money lost on hotel cancellations is lost in the translation. A booking platform has to normalise the policy, store exactly what was sold, show it honestly and enforce it the same way the supplier will.

Why this is harder than it looks

On a results page, “free cancellation” looks like a yes/no flag. Underneath, it is a time-dependent function: before one moment the penalty is zero, after it the penalty is one night, later it may be the whole stay. The problems come from the edges:

Time zones. A deadline of “2 days before arrival, 18:00” means nothing until you know whose 18:00 — the hotel’s, the supplier’s or UTC.
Penalty units. Suppliers express penalties as a number of nights, a percentage of the stay, or a fixed amount, sometimes in a different currency from the sale.
Changes between search and book. The policy returned at search can differ from the one returned at pre-book or in the booking confirmation. Only the last one counts.
Non-refundable rates. Some are truly non-refundable; others become non-refundable only after a deadline that has already passed for a short-notice stay.

The same discipline that applies to prices applies here: as with caching flight search, never sell a policy you cannot honour.

A normalised policy model

Convert every supplier’s format into one internal representation. A workable shape is an ordered list of penalty windows:

{
  "currency": "EUR",
  "windows": [
    { "from": null, "to": "2026-11-12T16:00:00Z", "penalty": { "type": "amount", "value": 0 } },
    { "from": "2026-11-12T16:00:00Z", "to": "2026-11-14T12:00:00Z", "penalty": { "type": "nights", "value": 1 } },
    { "from": "2026-11-14T12:00:00Z", "to": null, "penalty": { "type": "percent", "value": 100 } }
  ],
  "source": { "supplier": "example-supplier", "raw": "…original text or payload…" }
}

A few rules make this model reliable:

Store absolute instants in UTC. Convert relative rules (“48 hours before check-in”) at booking time, using the hotel’s time zone from your content data. Keep the hotel’s local time for display.
Resolve penalties to money when you can. “One night” is ambiguous when nightly rates vary; compute the amount from the booked rate breakdown and store it alongside the rule.
Keep the raw supplier policy. When a dispute arises, the original text or payload is the evidence. Your normalised version is an interpretation of it.
Treat unparseable as non-refundable. If a supplier sends a policy you cannot interpret with confidence, do not guess generously. Show the stricter reading and flag it for review.

Mapping supplier formats into this model is the same kind of work as hotel content mapping — tedious, supplier-specific and worth covering with tests built from real responses.

Search, pre-book and book

The policy should be fetched, normalised and compared at each step of the flow:

Search returns an indicative policy. Use it for filters such as “free cancellation” but mark it as indicative internally.
Pre-book or rate check returns the policy the supplier intends to apply. If it is stricter than what the customer saw, show the change before payment, just as you would for a price change.
Booking confirmation returns the policy that is actually in force. Store this one, attached to the booking, as an immutable record.

If the confirmed policy differs from the pre-book policy in a way that disadvantages the customer, treat it as an incident: flag the booking for operations rather than silently accepting it.

Showing it to customers

Clear presentation prevents most disputes:

show the deadline as a date and time in the hotel’s local time zone, with the zone named,
state the penalty as an amount in the customer’s currency, not as a rule they must calculate,
for multi-window policies, show a short timeline rather than a paragraph,
repeat the policy in the confirmation email and the booking page, from the stored record, not from a fresh lookup.

Many platforms show customers a deadline slightly earlier than the supplier’s, so a cancellation made at the last displayed minute can still reach the supplier in time. The buffer size is a business decision; make it configurable and apply it consistently in display and enforcement.

For B2B platforms selling through agents, show the agent both the customer-facing deadline and the supplier deadline. The agent may need the real one to handle a late request. The account-centred model for B2B travel applies here: which deadline each user sees depends on their role.

Enforcing it on cancellation

When a cancellation request arrives, the platform should:

Evaluate the stored policy at the current instant to compute the expected penalty.
Show the penalty and ask for confirmation if it is non-zero.
Cancel with the supplier, using an idempotency key so a retry cannot cause a duplicate request — see idempotency in booking and payment APIs.
Compare the supplier’s reported penalty with the expected one. A mismatch is a reconciliation item, not something to ignore.
Refund the customer according to your own terms, which may differ from the supplier’s if you applied a buffer or sell under your own policy.

Cancellations should also respect currency: if the booking was sold in one currency and the supplier charges penalties in another, the refund calculation needs the rates and rules described in multi-currency pricing and FX.

Deadlines as operational work

Deadlines are not just a cancellation concern. Bookings that sit unpaid or unconfirmed with a supplier, bookings that should be cancelled because a customer’s payment failed, and bookings where the agent asked to hold until a deadline all need a scheduler that acts before the penalty window opens. That is the same pattern as ticketing time limits and PNR housekeeping: track the deadline per booking, act a safe margin before it, and alert when an action fails.

Measure it

Track the bookings whose supplier penalty differed from the expected penalty, policies that failed to parse, policy changes between pre-book and booking, and cancellations processed within the buffer window. Those numbers show where a supplier mapping is wrong long before the losses add up. Observability for travel API integrations covers how to collect them per supplier.

Summary

A cancellation policy is a time-based function, not a flag. Normalise every supplier’s format into ordered penalty windows with UTC instants and resolved amounts, keep the raw original, and treat anything uncertain as stricter. Re-check the policy at pre-book, store the confirmed one immutably, display it in the hotel’s local time with amounts, enforce it idempotently, and reconcile the supplier’s penalty against your own calculation. Most hotel cancellation losses come from ambiguity; a precise model removes most of it.