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

# Waitlists

> Let guests queue for sold-out sessions and convert invitations into bookings

When a session sells out, brands with waitlists enabled can capture the demand instead of losing it: guests join the waitlist, and when capacity frees up they receive a **time-boxed invitation** to complete the booking.

## The flow

1. A session shows no availability (in the [sessions response](/api-reference/listings/get-listing-sessions), sold-out sessions of waitlist-enabled experiences appear with a `WAITLISTED` status).
2. Your UI offers "join the waitlist" instead of booking. You submit the guest's details with [Join waitlist](/api-reference/waitlists/join-waitlist).
3. When capacity opens (a cancellation, added inventory), Way invites entries in order. The invited guest gets a time-limited window to book.
4. Your checkout completes the booking as usual, passing the entry's ID as `waitlistEntryId` in the [book-bulk](/api-reference/carts-and-checkout/create-booking) cart item.

## Join a waitlist

The waitlist ID comes from the listing/experience data of waitlist-enabled experiences. Submit the same kind of information you'd collect for a booking:

```bash theme={null}
curl -X POST "$WAY_API/v1/brands/$WAY_BRAND_ID/waitlists/{waitlistId}/entries" \
  --header "Authorization: Bearer $WAY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "sessionStartDate": "2026-08-15",
    "sessionStartTime": "17:00",
    "sessionDuration": 90,
    "purchaser": { "firstName": "Alice", "lastName": "Rivera", "emailAddress": "alice@example.com", "phoneNumber": "+15550100" },
    "participants": [
      { "firstName": "Alice", "lastName": "Rivera", "priceTierName": "Adult" },
      { "firstName": "Ben", "lastName": "Rivera", "priceTierName": "Adult" }
    ]
  }'
```

All five fields are required - the entry is for a **specific session** (date + time + duration) and a specific party size.

## Handle the invitation

[Get waitlist entry](/api-reference/waitlists/get-waitlist-entry) returns the state of an entry that received an invitation - use it to render the invitation landing page:

* `status` - the entry's lifecycle state (an entry with an active invitation is `offered`).
* `expiresAt` - the invitation deadline. After it passes, the endpoint returns `410 Gone` and the spot moves on - treat that as "invitation expired" in your UI.
* The entry echoes the session (`startDate`, `startTime`, `sessionDuration`), `purchaser`, and `participants` you submitted, so the checkout can be prefilled.

Complete the booking within the window via the normal [checkout flow](/guides/build-a-booking-integration), including `"waitlistEntryId": "<entry id>"` in the cart item for both the payment intent and book-bulk calls - that's what ties the booking to the invitation and releases the held spot correctly.

[Get waitlist](/api-reference/waitlists/get-waitlist) returns the waitlist's configuration and current state if you need to display queue information.

<Note>
  Invitation notifications (email/SMS) are sent by Way. Your integration's job is the two ends: putting guests on the list, and converting the invitation link into a completed booking before `expiresAt`.
</Note>