Booking lifecycle

Booking lifecycle & statuses

A booking moves through a sequence of statuses, not a single “is it done yet” flag. Each status answers a different question — is it captured?, is the supplier holding the reservation?, is the ticket ready? — and the legal next steps depend on the current status.

Statuses

Status	Meaning
`UNCAPTURED`	Booking entry created but payment not yet captured. Does not lock price or inventory.
`PENDING`	Payment captured. Booking is confirmed with the supplier — show as confirmed to the customer. Ticket generation may still be in progress.
`COMPLETED`	Ticket generated and delivered. Available in the `tickets` array.
`CANCELLED`	Booking has been cancelled. Reached from `PENDING` or `COMPLETED`. Not always terminal — a reschedule moves the booking through `CANCELLED` and back to `PENDING` → `COMPLETED` (see Cancellation & reschedule lifecycle).
`FAILED`	Capture was attempted but rejected. The booking cannot move to any other status.
`CAPTURE_TIMEDOUT`	`UNCAPTURED` booking was not captured within 1 hour and can no longer be captured. The booking cannot move to any other status.

Transitions

From UNCAPTURED (after Create Booking), one of the following happens:

Remains UNCAPTURED until captured (no inventory or price lock)
→ PENDING when capture succeeds
→ FAILED when capture is attempted but rejected by Headout or the supplier
→ CAPTURE_TIMEDOUT when no capture is attempted within 1 hour

From PENDING:

→ COMPLETED when the ticket is generated (instant for hasInstantConfirmation: true, usually within ~30 min otherwise, p99 up to 1 day before the experience)
→ CANCELLED if the booking is cancelled before fulfilment

From COMPLETED:

→ CANCELLED if the booking is cancelled after the ticket has been generated (e.g. customer-initiated cancellation within policy, or a venue closure)

From CANCELLED:

Terminal for a genuine cancellation.
→ PENDING (then COMPLETED) only during a reschedule, which internally cancels and re-books the same booking. See Cancellation & reschedule lifecycle.

From FAILED or CAPTURE_TIMEDOUT: no further transitions. Create a new booking if the customer still wants to proceed.

Key notes

PENDING is confirmed. It means payment is captured and the supplier is holding the reservation. Treat it as a confirmed booking in your UI; ticket generation is a separate, often-delayed step.
COMPLETED is not the immediate next state after UNCAPTURED. Capture moves a booking to PENDING first; COMPLETED follows when the ticket is generated.
PENDING and COMPLETED can still move to CANCELLED — including Headout-initiated cancellations like venue closures.
CANCELLED is not always terminal. A reschedule round-trips the booking CANCELLED → PENDING → COMPLETED, so a CANCELLED seen while a reschedule is in flight may be transient. Don’t hard-code CANCELLED as a final state, especially when polling. See Cancellation & reschedule lifecycle.
UNCAPTURED is never sent via webhook. Other status transitions are.

Ticket generation & `hasInstantConfirmation`

Each product includes a hasInstantConfirmation flag:

Value	Meaning
`true`	Ticket generated immediately
`false`	Ticket generated with delay

Typical timelines:

Instant confirmation: < 1 minute (avg)
Delayed generation: ~30 minutes on average, p99 up to 1 day before experience for example, some venues like Louvre release tickets only 1 day before the experience date

For ticket generation delayed products:

Booking should still be shown as confirmed as soon as status reaches PENDING or beyond
Ticket generation is asynchronous
Voucher updates automatically when the ticket is ready

Start here

Build

Reference

Updates