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_HOLD bookings take a fast path: they are set to EXPIRED with no cancellation details, fee or notifications (removing an unconfirmed cart item).
  • All other cancellable bookings are set to CANCELLED with a cancellation object recording who cancelled, when, why and the fee.

Cancellation fee

  • cancelledBy: Organizer → fee 0 (full refund)
  • cancelledBy: Traveler while 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 / EXPIRED bookings cannot be cancelled again
  • cannot cancel more than 24 hours after the booking's start time
  • cancelledBy is required and must be one of Traveler, 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".

Requestbash
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

  • idstringrequired

    Booking UUID or booking code.

    Example:
    0b7f5f7e-1234-4c56-89ab-4d5e6f7a8b9c

Request bodyapplication/json, required

  • cancelledBystringrequired

    Who is cancelling — drives the fee (Organizer → always 0) and which email templates are sent.

    Allowed values:
    TravelerOrganizerResellerAdmin
    Example:
    Traveler
  • cancelledReasonstringnullable

    Optional free-text reason, stored on the cancellation record.

    Example:
    Change of plans
  • cancellationFeeAmountnumbernullable

    Optional fee override (the Hub's full/partial refund choice at cancel time). Applies only where the tiered policy would: cancelledBy: Organizer and traveler-after-alternatives keep their forced full refund (fee 0). Cannot exceed the booking price.

    Limits:
    minimum 0
    Example:
    30
Example: Traveler-initiated cancellation
Traveler-initiated cancellationjson
{
  "cancelledBy": "Traveler",
  "cancelledReason": "Change of plans"
}
Example: Organizer cancels (full refund)
Organizer cancels (full refund)json
{
  "cancelledBy": "Organizer",
  "cancelledReason": "Bad weather"
}

Responses

204

Booking cancelled (or ON_HOLD booking expired). No response body.

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."
    }
  ]
}