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).

Requestbash
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

  • idstringrequired

    Booking UUID or booking code.

    Example:
    V2REFUND001

Request bodyapplication/json

  • cancellationFeeAmountnumbernullable

    Override 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
Refund using the stored cancellation feejson
{}
Example: Keep a 10 EUR fee, refund the rest
Keep a 10 EUR fee, refund the restjson
{
  "cancellationFeeAmount": 10
}

Responses

200object

Refund processed.

  • messagestring

    Human-readable confirmation.

    Example:
    Booking has been refunded
Response 200json
{
  "message": "Booking has been refunded"
}

Errors

400

Validation failed. Inspect errors[].field and errors[].code.

401

Missing or invalid X-API-Key header.

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
  • typestring

    Error class.

    Allowed values:
    validation_errorclient_errorserver_error
    Example:
    validation_error
  • errorsobject[]
    Child fields
    • codestring

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

      Offending field, or null/'general' for non-field errors.

      Example:
      startTime
    • messagestring

      Human-readable message.

      Example:
      This field is required.
Response 400json
{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "field": "startTime",
      "message": "This field is required."
    }
  ]
}