Refund a booking payment
POST/v2/bookings/{id}/refund
Requires your API key in the X-API-Key header.
Refunds a booking's payment. Works for CANCELLED bookings (the normal
path, using the stored cancellation details) and for COMPLETED bookings
(late refunds — the booking status is untouched; the fee defaults to the
override or 0). NO_SHOW bookings are not refundable directly: cancel
first, so the refund lands in the statement as a cancellation refund (note
that cancellation is only possible up to 24 hours after the start time).
Optionally override the cancellation fee: the refunded amount is the final
price minus cancellationFeeAmount, and must be positive — a fee covering
the full price is refused (nothing to refund).
Gateway-charged payments are refunded through Stripe/Square.
Property-collected payments have no gateway to call — the endpoint records
the off-platform settlement by flipping payment.status to REFUNDED.
Bookings in a month whose organizer statement has already been invoiced are
refused (400) — a refund would silently rewrite the closed period.
A reseller (or BOTH-type partner) can refund a booking they own; a booking
outside their scope returns 404. Any other caller gets a 401 (empty body).
A missing gateway payment/intent is a 400 (nothing was
refunded); gateway errors surface as a 500 with
{"message": "...", "error": "..."} — the refund can be retried. Successful
refunds are recorded on the activity feed (booking.refunded, with the
acting user).
curl -X POST "https://api.turneo.co/v2/bookings/V2REFUND001/refund" \
-H "X-API-Key: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{}'Path parameters
idstringrequiredBooking UUID or booking code.
- Example:
V2REFUND001
Request bodyapplication/json
cancellationFeeAmountnumbernullableOverride for the cancellation fee: the refunded amount becomes final price minus this fee. Omit (or null) to use the fee already stored on the booking's cancellation record.
- Limits:
- minimum 0
- Example:
10
Example: Refund using the stored cancellation fee
{}Example: Keep a 10 EUR fee, refund the rest
{
"cancellationFeeAmount": 10
}Responses
200object
Refund processed.
messagestringHuman-readable confirmation.
- Example:
Booking has been refunded
{
"message": "Booking has been refunded"
}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."
}
]
}