Cancellation policies

Every stay you sell through OnSeason has cancellation terms. The terms say what cancelling costs and from when. OnSeason works them out for each stay, returns them on search results, quotes, and reservations, and calculates the charge when you cancel. You never compute deadlines yourself.

Who decides the policy

The property owner sets cancellation policies in OnSeason. An owner can set a policy for all their listings or for one listing, and for all sales channels or for one channel. Your channel is a sales channel of its own. Its key is your channel name in lowercase, and it appears as salesChannel on every set of terms you receive.

For a stay sold through your channel, OnSeason uses the most specific policy that exists:

source tells you which level the terms came from. Under DEFAULT, policyID and version are null and name is Non-refundable.

When a policy is configured, OnSeason also writes the terms into the booking notes in the owner's PMS, so the host's staff see the same terms as you.

Where the terms appear

All of these use the cancellation policy object.

Read the terms

Here are the terms of a stay that checks in on 5 December at 15:00 in Paris, quoted on 10 November for EUR 486:

{
  "policyID": "2f8d6b1a-9c3e-4d7f-8a1b-5e6c7d8f9a0b",
  "name": "Strict",
  "version": 1,
  "source": "TENANT",
  "salesChannel": "acme",
  "timeZone": "Europe/Paris",
  "fixedAt": "2026-11-10T10:00:00.000Z",
  "refundable": true,
  "refundableTag": "RFN",
  "freeCancellationUntil": "2026-11-21T14:00:00.000Z",
  "penalties": [
    { "from": "2026-11-21T14:00:00.000Z", "percentage": 50, "amount": 243, "currency": "EUR" },
    { "from": "2026-11-28T14:00:00.000Z", "percentage": 100, "amount": 486, "currency": "EUR" }
  ],
  "description": "Full refund if cancelled before 2026-11-21 15:00 (Europe/Paris). 50% refund (243.00 EUR) if cancelled before 2026-11-28 15:00 (Europe/Paris). No refund after that."
}

Read it as a timeline:

• Until freeCancellationUntil, 21 November at 15:00 Paris time, cancelling is free.
• From 21 November at 15:00, cancelling costs 50%, which is EUR 243.
• From 28 November at 15:00, cancelling costs 100%, which is EUR 486.

penalties lists what cancelling costs from each moment. The percentage only rises, and the last step is always 100%. If something is already due when the terms are fixed, the first step starts at fixedAt and freeCancellationUntil is null.

refundable is false only when cancelling already refunds nothing. refundableTag carries the same fact as the wholesale codes RFN and NRFN.

How deadlines are set

A policy is written in days before check-in. For example, "full refund until 14 days before arrival, half until 7 days". OnSeason turns each day count into an instant:

• The deadline falls on the calendar day that many days before check-in, at the property's check-in time. When the listing has no check-in time, OnSeason uses 15:00.
• The time is local to the property. OnSeason uses the listing's timeZone. When the listing has none, OnSeason derives the zone from its coordinates, and falls back to UTC when it can't.
• A deadline that crosses a daylight-saving change keeps its local hour.

Every timestamp is returned in UTC. description shows the same deadlines in the property's local time, with the zone name.

When the terms are fixed

The terms are fixed when you create the quote, and fixedAt records that moment. The quoteToken carries them. When you book with the token, the reservation gets exactly the quoted terms, even if the owner changes the policy in the meantime. The reservation keeps those terms for its whole life.

Search terms are not fixed. They show what a quote would return at the time of the search. The policy, deadlines, and percentages match the quote unless the owner changes the policy in between. The amounts are shares of the search price, totalPrice when present or else avgNightlyPrice times the nights. The quote works the amounts out again on the quoted total.

Show the terms to the guest

1. Show the terms on search results when they are present, for example "Free cancellation until 21 Nov".
2. At checkout, show the terms from the quote. These are the terms the guest books under.
3. After booking, store cancellationPolicy from the reservation response and show it in the confirmation and in booking management.

You can show description as it is, or build your own wording from freeCancellationUntil and penalties. If you build your own, convert the UTC instants to the property's timeZone, not the guest's, so your deadlines match the host's.

What happens when you cancel

When you cancel a reservation with your API key, OnSeason records the cancellation as CHANNEL and works out cancellationCharge from the booked terms. It uses the moment OnSeason received your request.

{
  "id": "9fa05abc-daf0-4ee4-a9e6-f959c2e8a421",
  "status": "CANCELLED",
  "cancelledAt": "2026-11-25T09:00:00.000Z",
  "cancelledBy": "CHANNEL",
  "cancellationCharge": {
    "penaltyPercentage": 50,
    "penaltyAmount": 243,
    "refundPercentage": 50,
    "refundAmount": 243,
    "currency": "EUR"
  }
}

The charge is in the reservation's currency and is the figure both sides work from. The API doesn't move money: it doesn't charge the guest or issue refunds. How you and OnSeason settle the penalty and the refund is set in your commercial agreement. See Current limits.

A reservation can also be cancelled outside your integration, for example by the host in their PMS. Its status changes to CANCELLED, but cancelledBy and cancellationCharge stay null. OnSeason calculates a charge only for cancellations requested through the API.