Waitlist

When a bookable is sold out and the event has waitlist_enabled, customers can join the waitlist straight from the widget. Promotion is FIFO per bookable (by waitlist_entries.created_at).

How it works

1. The customer joins → a WaitlistEntry is created in waiting.
2. Capacity frees up (booking cancelled, hold expired, booking edited) → OfferSpotOnCapacity promotes the next waiting entry: state offered, a 64-char offer_token, and expires_at = now + 24 h (OfferSpotOnCapacity::DEFAULT_OFFER_TTL_HOURS). The customer gets a WaitlistSpotOfferedNotification with the /waitlist/claim/{token} link.
3. The customer opens the link — they must be logged in as the entry's user — and clicks Claim: state claimed, then a redirect to the booking review page pre-seeded with the bookable and people count.
4. Completing that booking marks the entry fulfilled (the waitlist_entry_id is carried through; a BookingCreated listener is the safety net).
5. Decline → cancelled and the next waiting entry is promoted immediately.
6. waitlist:expire-claims (every 5 min) expires stale offered/claimed entries and promotes the next in line.

States

waiting → offered → claimed → fulfilled
            ↘ expired   ↘ cancelled (declined)

Two kinds of entry

waitlist_entries.kind splits the table in two lifecycles that never mix:

• capacity (default) — the sold-out flow above: account users queueing for freed capacity, FIFO promotion, claim link gated by token and the matching authenticated user.
• walkin — the door queue: staff take same-day walk-in parties on an Area, the guest is a name/phone pair (no account), the offer goes out over SMS/mail, and the claim page is token-only. Walk-in rows never auto-promote and are seated by hand — see door ops.

Permissions

Owner, admin and manager see waitlist state on the widget and in the booking flow. Joining and claiming are customer actions — the claim link is gated by the 64-char token and the matching authenticated user, no staff role needed. Walk-in queue writes need bookings.seat.