Cancel a reservation
Cancel a confirmed reservation and get the charge under its booked terms.
DELETE/api/v1/reservation/{id}
Cancels a CONFIRMED reservation that you created with your API key. OnSeason sends the cancellation to the PMS, records it as CHANNEL, and works out the charge from the booked cancellation terms at the moment it received the request. The request has no body.
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | UUID | OnSeason reservation ID, not providerReservationID. |
Example
curl --request DELETE \
"https://zepl-staging.calry.app/api/v1/reservation/9fa05abc-daf0-4ee4-a9e6-f959c2e8a421" \
--header "x-calry-api-key: <API_KEY>"{
"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"
}
}Response
| Field | Type | Description |
|---|---|---|
id | UUID | OnSeason reservation ID. |
status | enum | CANCELLED, or CANCELLATION_PENDING when the PMS has no cancellation API and the booking is cancelled there by hand. |
cancelledAt | date-time | When OnSeason recorded the cancellation. |
cancelledBy | enum | CHANNEL for cancellations made with a channel API key. |
cancellationCharge | object | What the booked terms charge for this cancellation. See below. |
Cancellation charge
| Field | Type | Description |
|---|---|---|
penaltyPercentage | number | Share of the booked total the guest forfeits. |
penaltyAmount | number | Penalty in currency. |
refundPercentage | number | Share of the booked total to refund. 100 - penaltyPercentage. |
refundAmount | number | Refund in currency. |
currency | string | The reservation's currency. |
The charge records what the terms say is due. The API doesn't charge or refund anyone.
Status codes
| Status | Meaning |
|---|---|
200 | Reservation cancelled, or already CANCELLATION_PENDING, in which case nothing changes. |
400 | The ID is invalid, or the reservation is not CONFIRMED. |
401 | The API key is missing or invalid. |
403 | The API key is not allowed to cancel reservations. |
404 | No reservation with this ID was created with your API key. |
If a cancel request times out, get the reservation and check status before you send it again.