Create a booking — API

POST/api/v1/bookings

Scope: bookings:writeIdempotency-Key required

Books seats on a departure, exactly as a manual booking made in Awrora does: the same capacity check (including seats held in someone else's checkout), the same customer record, the same timeline entry and the same confirmation email. The booking is recorded with source "api". Prices come from the experience's price tiers — the body carries counts, never amounts. Requires the "bookings:write" scope and an "Idempotency-Key" header.

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

experience_date_idrequired

stringuuid

The departure to book, from GET /v1/availability. A departure that belongs to another organization answers 404, exactly like one that does not exist.

guestsrequired

object[]

At least one guest line. Several lines may use different price tiers.

Field	Type	Description
`tier_id`required	string≥ 1 chars	Price tier id from the experience resource ("price_tiers[].id"). Unknown tiers are rejected with "validation_failed".
`count`required	integermin 1 · max 500	How many guests on this tier. At least 1.

add_ons

object[]

Optional add-ons. Requires the "Add-ons" app to be enabled for the organization.

customerrequired

object

Who the booking is for.

Field	Type	Description
`name`required	string≥ 1 chars · ≤ 200 chars	The guest's name, as it should appear on the booking.
`email`required	stringemail · ≤ 200 chars	The guest's email. Also the key in the customer register: an existing customer with this email is reused, never duplicated.
`phone`	string≤ 200 chars	The guest's phone. Swedish format ("+46701234567" or "0701234567") or omitted — an unparseable number is rejected rather than stored as typed.

note

string≤ 2000 chars

Free-text note stored on the booking and shown to staff.

paymentrequired

string

How the booking is paid. "pay_on_site": confirmed, the guest pays the operator on arrival (the platform on-site fee is accrued, exactly as for a checkout booking). "invoice": confirmed and flagged for invoicing by staff. "external_paid": confirmed and already paid somewhere else — no card is charged and no invoice is created. There is no card option: this API never takes payment.

"pay_on_site""invoice""external_paid"

send_confirmation_email

booleandefault true

Send the organization's booking confirmation email to the guest. Set false when your own system already told them.

notify_staff

booleandefault true

Send the organization's internal "new booking" notification email to its staff, the same one a checkout booking triggers. Honors the organization's own notification settings: if they have switched that notification off, nothing is sent either way. Set false when your integration already tells staff itself.

Example request#

bash

curl -X POST "https://your-site.awrora.app/api/v1/bookings" \
  -H "Authorization: Bearer $AWRORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "experience_date_id": "3f6c1f0e-8a2b-4f4e-9d7a-2b1c5e0a9f11",
  "guests": [
    {
      "tier_id": "tier_8f2k3n",
      "count": 1
    }
  ],
  "add_ons": [
    {
      "id": "3f6c1f0e-8a2b-4f4e-9d7a-2b1c5e0a9f11",
      "count": 1
    }
  ],
  "customer": {
    "name": "string",
    "email": "anna@example.com",
    "phone": "string"
  },
  "note": "string",
  "payment": "pay_on_site",
  "send_confirmation_email": true,
  "notify_staff": true
}'

Responses#

200The booking that was created — the same shape GET /v1/bookings/{id} returns. Returned when nothing new was created — the resource already existed, or this is a replay of an earlier request with the same Idempotency-Key.
201The booking that was created — the same shape GET /v1/bookings/{id} returns.
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".
409The request conflicts with the current state — codes "insufficient_capacity" (carries "seats_available"), "conflict", or "idempotency_in_progress" when another request with the same Idempotency-Key is still running.
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"
}