Cancellation Policies

Cancellation policies define what a user will be charged if they cancel a booking between specific dates. They appear in Rooms & Rates, Pricing, Book confirmation, and Booking Details responses. You are required to display them accurately at every stage — this is verified during certification.

Policy fields

start

Start of the window during which this penalty applies. ISO 8601 datetime with timezone offset.

end

End of the window. Cancellations after this datetime fall into the next policy window.

valueType

How the penalty is expressed. One of: Amount, Percentage, Nights.

value

The raw value — a currency amount, a percentage (0–100), or a number of nights.

estimatedValue

Always a currency amount. The actual charge the user will incur. Use this field to display the penalty to users — regardless of valueType.

The three valueType values

Amount

The penalty is a fixed currency amount. value and estimatedValue will be the same number.

value: 709
estimatedValue: 709

Percentage

The penalty is a percentage of the total booking. value is 0–100. estimatedValue is the calculated amount to charge.

value: 50
estimatedValue: 354.50

Nights

The penalty is a number of nights' cost. value is the night count. estimatedValue is the calculated amount.

value: 1
estimatedValue: 709

Always display estimatedValue to the user — not value. The estimatedValue is always a currency amount regardless of valueType, making it safe to display directly without conversion logic on your side.

Reading a policy array — three real examples

Free cancellation window Cancellation before 14 Mar — no charge

{
  "value": 0,
  "valueType": "Amount",
  "estimatedValue": 0,
  "start": "2025-02-10T00:00:00+00:00",
  "end": "2025-03-14T11:00:00+00:00"
}

estimatedValue: 0 means the booking is fully refundable if cancelled before 14 Mar 11:00 UTC. Display this as "Free cancellation until 14 March 2025".

Partial penalty window Cancellation 14–17 Mar — partial charge

{
  "value": 709,
  "valueType": "Amount",
  "estimatedValue": 709,
  "start": "2025-03-14T11:00:00+00:00",
  "end": "2025-03-17T00:00:00+00:00"
}

If cancelled between 14 Mar 11:00 and 17 Mar 00:00 UTC, the user is charged $709. Display this as "Cancellation fee of $709 from 14 March 2025".

Full penalty window Cancellation after 17 Mar — full charge

{
  "value": 3424,
  "valueType": "Amount",
  "estimatedValue": 3424,
  "start": "2025-03-17T00:00:00+00:00",
  "end": "2025-03-17T00:00:00+00:00"
}

After 17 Mar, the full booking value of $3,424 is non-refundable. Note that start and end can be the same datetime — this means the policy applies from that point until check-in.

Display requirements — certification

You must display cancellation policies at every step: Hotel Details page, Checkout page, Booking Confirmation page, and My Trips / Booking Details page. The policy shown must match the API response exactly. Timezone matters — always display the time in the user's local timezone, not raw UTC. Failing to display policies correctly is the most common reason integrations fail certification.