> ## Documentation Index
> Fetch the complete documentation index at: https://partner.headout.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Booking lifecycle

> The statuses a booking moves through, the transitions between them, and when tickets appear.

## 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](https://partner.headout.com/docs/guide/concepts/cancellation-and-reschedule.md#cancellation-%26-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](https://partner.headout.com/docs/guide/concepts/cancellation-and-reschedule.md#cancellation-%26-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](https://partner.headout.com/docs/guide/concepts/cancellation-and-reschedule.md#cancellation-%26-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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.