Event Waitlist Reference

What This Covers#

This reference lists:

• waitlist-related event fields
• the three waitlist modes
• registration statuses that matter operationally
• confirmed admin-side actions in the Filament panel
• known notes and limitations

Waitlist-Related Event Fields#

Capacity#

The base seat limit for the event.

Operationally:

• if blank or 0, the event is treated as unlimited
• waitlists only make sense when capacity is greater than 0

Overbook seats (%)#

Optional percentage-based overbook buffer.

Operationally:

• increases the effective seat limit
• if this is set above 0, the fixed overbook field is cleared to avoid conflicting settings

Overbook seats (fixed)#

Optional fixed-seat overbook buffer.

Operationally:

• increases the effective seat limit by a fixed number of seats
• if this is set above 0, the percentage field is cleared to avoid conflicting settings

Enable waitlist#

Turns waitlisting on or off for the event.

Operationally:

• when off, the event does not use waitlist handling
• turning it off resets Waitlist mode back to manual

Waitlist mode#

The event-level mode selected by staff.

Available values:

• manual
• offered
• automatic

UI labels:

• Manual (staff approves)
• Offered (invite next person to claim)
• Automatic (auto-promote next person)

waitlist_offer_expires_minutes#

The offer window length used for waitlist offers.

Confirmed behavior:

• defaults to 30 minutes when not set
• code accepts values above 0 and up to 240

Note: This field is confirmed in the model/controller behavior, but a standard tenant-facing form field for it was not confirmed in the audited event form snippet.

Waitlist Modes#

manual#

Meaning:

• staff reviews the queue and decides what to do next

Operationally:

• full-event signups can still become waitlisted
• the system does not auto-promote the next person
• staff can create an offer manually from the dashboard
• free waitlisted registrations can be manually promoted from the registrations table

offered#

Meaning:

• the next person gets a time-limited chance to claim the seat

Operationally:

• the registrant remains waitlisted until they successfully claim
• active offers reserve capacity
• offer links are signed and time-limited
• the claim flow requires the same email address used to join the waitlist

automatic#

Meaning:

• the system promotes the oldest eligible waitlisted registration when seats become available

Operationally:

• only runs when the event is in automatic mode
• only runs when waitlisting is enabled
• only runs when capacity is greater than 0
• oldest waitlisted registrations are processed first

For free registrations:

• the promoted person becomes confirmed
• a confirmation email is queued

For paid registrations:

• the promoted person becomes pending
• a "promoted" email is queued so they can complete payment

Relevant Registration Statuses#

waitlisted#

The registrant does not currently have a confirmed seat.

Waitlist-related timestamps can also exist on this record:

• waitlisted_at
• waitlist_offered_at
• waitlist_expires_at
• waitlist_claimed_at

pending#

The registrant is in an active payment-hold state.

Operationally:

• pending registrations reserve capacity
• automatic promotion for a paid waitlisted registrant moves the person into pending

confirmed#

The registrant has a seat.

Operationally:

• confirmed registrations reserve capacity
• only confirmed registrations can be manually checked in from the registrations table

cancelled#

The registration is no longer active.

Operationally:

• can free seats
• seat release can trigger waitlist processing through the status service

refunded#

The registration is no longer active and has been refunded.

Operationally:

• can free seats
• refunds are a confirmed trigger for automatic waitlist promotion in the audited implementation

failed#

The registration did not complete successfully.

Operationally:

• failed registrations are not treated like confirmed seats
• automatic promotion clears failed-state fields when moving a registration forward

Waitlist Offer Lifecycle Fields#

These registration-level fields are confirmed:

• waitlisted_at
• waitlist_offered_at
• waitlist_expires_at
• waitlist_claimed_at

Related metadata can also be stored under:

• waitlist.mode
• waitlist.captured_at
• waitlist.promoted_at
• waitlist.pricing_snapshot
• waitlist.offer.token
• waitlist.offer.offered_at
• waitlist.offer.expires_at
• waitlist.offer.claimed_at
• waitlist.offer_expired_at

Confirmed Admin Actions#

Event edit page#

Confirmed action:

• Waitlist

This opens the dedicated Manage Waitlist page in a new tab.

Manage Waitlist page#

Confirmed columns:

• name
• email
• waitlisted date/time
• offer expiry
• seats

Confirmed filters:

• Active offer
• No active offer

Confirmed actions:

• Send offer
• Expire offer

Important behavior:

• Send offer checks capacity first
• Send offer refreshes or creates offer metadata
• Send offer does not queue the offer email from this page
• Expire offer clears offer metadata so the offer can no longer be claimed

Event registrations table#

Confirmed waitlist-related filters:

• Offered (active)

Confirmed waitlist-related actions:

• Send offer email
• Resend waitlist email
• Expire / revoke offer
• Promote (free)

Confirmed view-side footer actions in the registration slide-over:

• Resend waitlist email
• Resend offer email
• Resend confirmation email

Attendance and check-in actions relevant to waitlists#

Confirmed behavior:

• manual check-in only allows confirmed registrations
• deleted registrations cannot be manually checked in
• already checked-in registrations are blocked from duplicate manual check-in

Operational implication:

• a waitlisted person must first become confirmed before they can be checked in

Notes and Limitations#

Note: The audited implementation confirms automatic promotion logic, manual offer creation, and free manual promotion. It does not confirm a staff-side "force confirm paid waitlisted registration without payment" action.

Note: Active offers reserve capacity. A seat is not truly available again until the offer is claimed, expired, revoked, or otherwise cleared.

Note: Offer expiry cleanup is also handled by the events:expire-stale-registrations command, which clears expired waitlist offers and records waitlist.offer_expired_at in metadata.

TODO: If your operations team expects a configurable waitlist offer window in the event form, confirm with product whether that field is intentionally hidden, custom, or still pending a tenant-facing UI.

Related Topics#

• How to Manage Event Waitlists
• How Waitlists Work
• Events Reference