# Waitlist

# Waitlist

Quando un prenotabile è sold-out e l'evento ha `waitlist_enabled`, i clienti possono entrare in lista d'attesa direttamente dal widget. La promozione è FIFO per prenotabile (per `waitlist_entries.created_at`).

## Come funziona

1. Il cliente entra in lista → viene creata una `WaitlistEntry` in `waiting`.
2. Si libera capacità (prenotazione annullata, hold scaduto, prenotazione modificata) → `OfferSpotOnCapacity` promuove la prossima voce in attesa: stato `offered`, un `offer_token` da 64 caratteri e `expires_at` = ora + **24 h** (`OfferSpotOnCapacity::DEFAULT_OFFER_TTL_HOURS`). Il cliente riceve una `WaitlistSpotOfferedNotification` con il link `/waitlist/claim/{token}`.
3. Il cliente apre il link — deve essere loggato **come l'utente della voce** — e clicca **Reclama**: stato `claimed`, poi redirect alla pagina di riepilogo prenotazione pre-compilata con prenotabile e numero di persone.
4. Completare quella prenotazione porta la voce a `fulfilled` (il `waitlist_entry_id` viene propagato; un listener su `BookingCreated` fa da rete di sicurezza).
5. **Declina** → `cancelled` e la prossima voce in attesa viene promossa subito.
6. `waitlist:expire-claims` (ogni 5 min) scade le voci offered/claimed stantie e promuove la prossima in coda.

## Stati

```
waiting → offered → claimed → fulfilled
            ↘ expired   ↘ cancelled (declinata)
```

## Due tipi di voce

`waitlist_entries.kind` divide la tabella in due cicli di vita che non si mescolano mai:

- **`capacity`** (default) — il flusso sold-out qui sopra: utenti con account in coda per capacità liberata, promozione FIFO, link di reclamo coperto da token **e** utente autenticato corrispondente.
- **`walkin`** — la [coda alla porta](/docs/venue/door-ops): lo staff prende i gruppi walk-in in giornata su un'Area, l'ospite è una coppia nome/telefono (nessun account), l'offerta parte via SMS/mail e la pagina di reclamo è a solo token. Le voci walk-in non promuovono mai in automatico e vengono accomodate a mano — vedi door ops.

## Permessi

Owner, admin e manager vedono lo stato della waitlist sul widget e nel flusso di prenotazione. Entrare in lista e reclamare sono azioni del cliente — il link di reclamo è coperto dal token a 64 caratteri **e** dall'utente autenticato corrispondente, nessun ruolo staff necessario. Le scritture sulla coda walk-in richiedono `bookings.seat`.


---
> Source: https://placeful-app.com/docs/bookings/waitlist