# Cancel a booking

`POST /api/v1/bookings/{id}/cancel`

Cancels a booking and runs the organization's cancellation flow: refund according to the chosen mode, cancellation email to the guest, notice to staff. Cancelling an already cancelled booking is not an error — it answers 200 with the unchanged booking, so a retry is always safe. Requires the "bookings:write" scope and an "Idempotency-Key" header.

Scope: `bookings:write`
Idempotency-Key: required

## Parameters

- `id` (path, string, required) — Awrora id (UUID) for the booking.
- `Idempotency-Key` (header, string, required) — A unique key for this request, 8-200 characters (a UUID is a good choice). Retrying with the same key replays the first response verbatim — same status, same body, plus "Idempotent-Replayed: true" — instead of acting twice. Reusing a key with a different body answers 422.

## Request body

- `refund` ("auto" | "none") — How to handle money already taken. "auto" (default) follows the organization's refund policy, the same way the admin cancel button does. "none" keeps the money. Bookings without a card payment are unaffected either way.
- `reason` (string) — Why it was cancelled. Stored with the cancellation for staff to read.

## Responses

- `200` — The booking, now cancelled.
- `400` — Invalid request — codes "validation_failed" or, on an endpoint that requires one, "idempotency_key_required".
- `401` — Missing, invalid, revoked or expired API key — codes "api_key_missing", "api_key_invalid", "api_key_revoked", "api_key_expired".
- `403` — The API app is off, the plan does not include the API, or the key lacks the required scope — codes "app_not_enabled", "plan_upgrade_required", "insufficient_scope" (the last carries "required_scope").
- `404` — No such resource. The same response is returned for a resource that belongs to another organization — code "not_found".
- `422` — The request was understood but cannot be fulfilled as asked — codes "validation_failed" or "idempotency_key_reused" (the same Idempotency-Key was already used with a different body).
- `429` — Rate limit exceeded — code "rate_limited". See the x-ratelimit-* headers.
- `500` — Something went wrong on our side — code "internal_error".

## Response `200`

- `id` (string, required) — Awrora id (UUID) for the booking.
- `booking_number` (integer | null, required) — Sequential booking number within the organization, or null for legacy rows.
- `status` ("pending" | "confirmed" | "cancelled", required) — pending = created, awaiting payment; confirmed = active; cancelled = cancelled.
- `source` (string | null, required) — Where the booking came from: online, admin, agency, ai or api.
- `created_at` (string, required) — ISO 8601 timestamp with offset.
- `updated_at` (string, required) — ISO 8601 timestamp with offset.
- `experience` (object, required) — The experience that was booked.
- `departure` (object, required) — The departure that was booked.
- `customer` (object, required) — The guest details captured at checkout. Not the customer record — see /v1/customers.
- `guests` (object[], required) — Guest lines. May be empty for legacy rows.
- `add_ons` (object[], required) — Add-on lines. Empty when none were bought.
- `totals` (object, required) — Money totals for the booking.
- `payment` (object, required) — How the booking is paid, and where that payment stands.
- `note` (string | null, required) — Free-text note from the buyer or staff, or null.
- `manage_url` (string | null, required) — Link where the guest can open and finish their own booking. Only returned to keys with the "bookings:write" scope — read-only keys and webhook/event payloads always get null, because anyone holding the link can see the booking and complete it. Also null when no valid link exists (no token, or the token has expired). Treat it as a secret.

## Example

```bash
curl -X POST "https://your-site.awrora.app/api/v1/bookings/id_8f2k3n/cancel" \
  -H "Authorization: Bearer $AWRORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "refund": "auto",
  "reason": "string"
}'
```