Cancel a booking
POST/v2/bookings/{id}/cancel
Requires your API key in the X-API-Key header.
Cancels a booking and frees its reserved capacity and resources.
ON_HOLDbookings take a fast path: they are set toEXPIREDwith no cancellation details, fee or notifications (removing an unconfirmed cart item).- All other cancellable bookings are set to
CANCELLEDwith acancellationobject recording who cancelled, when, why and the fee.
Cancellation fee
cancelledBy: Organizer→ fee 0 (full refund)cancelledBy: Travelerwhile alternative slots were offered → fee 0- otherwise the experience's tiered refund policy applies (tier chosen by hours until start); an experience with no refund policy is non-refundable — the full price becomes the fee.
cancellationFeeAmount(optional) overrides the policy-computed fee. It never applies to the two full-refund branches above and cannot exceed the booking price.
Guards (400)
- already
CANCELLED/EXPIREDbookings cannot be cancelled again - cannot cancel more than 24 hours after the booking's start time
cancelledByis required and must be one ofTraveler,Organizer,Reseller,Admin
Side effects
Externally-sourced bookings (Bokun/Regiondo) are cancelled at the provider. A refund for the non-fee remainder is issued automatically for gateway-collected payments. Cancellation emails are sent (organizer-cancelled vs traveler/reseller-cancelled templates), the reseller is notified, and the hotel PMS folio is updated to "Cancelled".
curl -X POST "https://api.turneo.co/v2/bookings/0b7f5f7e-1234-4c56-89ab-4d5e6f7a8b9c/cancel" \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"cancelledBy": "Traveler",
"cancelledReason": "Change of plans"
}'Path parameters
idstringrequiredBooking UUID or booking code.
- Example:
0b7f5f7e-1234-4c56-89ab-4d5e6f7a8b9c
Request bodyapplication/json, required
cancelledBystringrequiredWho is cancelling — drives the fee (Organizer → always 0) and which email templates are sent.
- Allowed values:
TravelerOrganizerResellerAdmin- Example:
Traveler
cancelledReasonstringnullableOptional free-text reason, stored on the cancellation record.
- Example:
Change of plans
cancellationFeeAmountnumbernullableOptional fee override (the Hub's full/partial refund choice at cancel time). Applies only where the tiered policy would:
cancelledBy: Organizerand traveler-after-alternatives keep their forced full refund (fee 0). Cannot exceed the booking price.- Limits:
- minimum 0
- Example:
30
Example: Traveler-initiated cancellation
{
"cancelledBy": "Traveler",
"cancelledReason": "Change of plans"
}Example: Organizer cancels (full refund)
{
"cancelledBy": "Organizer",
"cancelledReason": "Bad weather"
}Responses
204
Booking cancelled (or ON_HOLD booking expired). No response body.
Errors
- 400
Validation failed. Inspect
errors[].fieldanderrors[].code.- 401
Missing or invalid
X-API-Keyheader.- 403
The API key is valid but not allowed to perform this action on this resource.
- 404
The resource does not exist or belongs to another partner (existence is not leaked across partners).
Error body
typestringError class.
- Allowed values:
validation_errorclient_errorserver_error- Example:
validation_error
errorsobject[]Child fields
codestringMachine-readable error code.
- Example:
required
fieldstringnullableOffending field, or null/'general' for non-field errors.
- Example:
startTime
messagestringHuman-readable message.
- Example:
This field is required.
{
"type": "validation_error",
"errors": [
{
"code": "required",
"field": "startTime",
"message": "This field is required."
}
]
}