Cancel a booking — API

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

Scope: bookings:writeIdempotency-Key required

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.

Path parameters#

Field	Type	Description
`id`required	string	Awrora id (UUID) for the booking.

Headers#

Field	Type	Description
`Idempotency-Key`required	string≥ 8 chars · ≤ 200 chars	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#

Field	Type	Description
`refund`	stringdefault "auto"	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. `"auto""none"`
`reason`	string≤ 200 chars	Why it was cancelled. Stored with the cancellation for staff to read.

Example request#

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"
}'

Responses#

200The booking, now cancelled.
400Invalid request — codes "validation_failed" or, on an endpoint that requires one, "idempotency_key_required".
401Missing, invalid, revoked or expired API key — codes "api_key_missing", "api_key_invalid", "api_key_revoked", "api_key_expired".
403The 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").
404No such resource. The same response is returned for a resource that belongs to another organization — code "not_found".
422The 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).
429Rate limit exceeded — code "rate_limited". See the x-ratelimit-* headers.
500Something went wrong on our side — code "internal_error".

Response 200

Field Type Description

idrequired

string

Awrora id (UUID) for the booking.

booking_numberrequired

integer | null

Sequential booking number within the organization, or null for legacy rows.

statusrequired

string

pending = created, awaiting payment; confirmed = active; cancelled = cancelled.

"pending""confirmed""cancelled"

sourcerequired

string | null

Where the booking came from: online, admin, agency, ai or api.

created_atrequired

string

ISO 8601 timestamp with offset.

updated_atrequired

string

ISO 8601 timestamp with offset.

experiencerequired

object

The experience that was booked.

departurerequired

object

The departure that was booked.

customerrequired

object

The guest details captured at checkout. Not the customer record — see /v1/customers.

guestsrequired

object[]

Guest lines. May be empty for legacy rows.

Field Type Description

tier_idrequired

string | null

Id of the price tier, or null for legacy fixed guest types.

tier_labelrequired

string

Guest type as shown to the buyer, e.g. "Vuxen".

countrequired

integermin -9007199254740991 · max 9007199254740991

Number of guests of this type.

unit_pricerequired

object | null

Price per guest of this type.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

add_onsrequired

object[]

Add-on lines. Empty when none were bought.

Field Type Description

idrequired

string

Id of the add-on.

labelrequired

string

Add-on name as shown to the buyer.

countrequired

integermin -9007199254740991 · max 9007199254740991

Quantity booked.

unit_pricerequired

object | null

Price per unit.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

totalsrequired

object

Money totals for the booking.

Field Type Description

subtotalrequired

object | null

Sum of guests and add-ons before discounts.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

discountrequired

object | null

Total discount applied. Zero when none.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

gift_cardrequired

object | null

Amount paid with gift cards. Zero when none.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

totalrequired

object | null

Amount the buyer owes or paid, after discounts and gift cards.

Field	Type	Description
`amount_minor`required	integermin -9007199254740991 · max 9007199254740991	Amount in the currency's minor unit (öre, cents). 120000 means 1200.00.
`currency`required	string	ISO 4217 currency code, uppercase. For example "SEK".

paymentrequired

object

How the booking is paid, and where that payment stands.

Field	Type	Description
`method`required	string \| null	Payment method as recorded at checkout, e.g. "Kort" or "Betala på plats".
`source`required	string	Where the money came from, not whether it arrived. stripe = Awrora took the payment (card or Stripe invoice); on_site = the guest pays the operator in person; external = the booking was paid in the operator's previous booking system and migrated in, so no refund can be issued through Awrora. Unlike "method", which is a human receipt label and is translated, this is a stable machine value. `"stripe""on_site""external"`
`status`required	string	paid = settled; pending = awaiting payment; scheduled = will be invoiced later; cancelled = booking or invoice voided; unpaid = written off; unknown = no payment state recorded. `"paid""pending""scheduled""cancelled""unpaid""unknown"`

noterequired

string | null

Free-text note from the buyer or staff, or null.

manage_urlrequired

string | null

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.

200 response

{
  "id": "res_8f2k3n",
  "booking_number": -9007199254740991,
  "status": "pending",
  "source": "string",
  "created_at": "string",
  "updated_at": "string",
  "experience": {
    "id": "res_8f2k3n",
    "title": "string",
    "slug": "string"
  },
  "departure": {
    "id": "res_8f2k3n",
    "starts_at": "string",
    "ends_at": "string"
  },
  "customer": {
    "name": "string",
    "email": "anna@example.com",
    "phone": "string"
  },
  "guests": [
    {
      "tier_id": "tier_8f2k3n",
      "tier_label": "string",
      "count": -9007199254740991,
      "unit_price": {
        "amount_minor": -9007199254740991,
        "currency": "SEK"
      }
    }
  ],
  "add_ons": [
    {
      "id": "res_8f2k3n",
      "label": "string",
      "count": -9007199254740991,
      "unit_price": {
        "amount_minor": -9007199254740991,
        "currency": "SEK"
      }
    }
  ],
  "totals": {
    "subtotal": {
      "amount_minor": -9007199254740991,
      "currency": "SEK"
    },
    "discount": {
      "amount_minor": -9007199254740991,
      "currency": "SEK"
    },
    "gift_card": {
      "amount_minor": -9007199254740991,
      "currency": "SEK"
    },
    "total": {
      "amount_minor": -9007199254740991,
      "currency": "SEK"
    }
  },
  "payment": {
    "method": "string",
    "source": "stripe",
    "status": "paid"
  },
  "note": "string",
  "manage_url": "https://example.com/webhooks/awrora"
}