Why Waitlists Exist
Waitlists help a nonprofit keep registration open in a controlled way after an event has reached capacity.
That matters because "full" is often not the end of the story. People cancel. Payments fail. Guests drop out. Staff may want to refill seats without manually rebuilding the list every time.
In Altrinum, the waitlist is tied directly to the event's capacity logic, registration statuses, payment flow, and admin tools. That makes it much more useful operationally than a simple spreadsheet of names.
What Counts as "Full"
An event is considered full when it does not have enough available seat units for the current registration attempt.
The system does not just count confirmed registrations. Capacity can also be held by:
confirmedregistrationspendingregistrations- waitlisted registrations with an active offer
That is why an event can still behave as full even after one seat appears to open up.
Example:
If one confirmed registrant cancels but another waitlisted registrant already has an active offer, that offered registrant is still reserving the seat.
What Happens When the Event Reaches Capacity
When a new registration attempt would push the event over the available seats:
- the system checks whether waitlisting is enabled
- if it is enabled, the registration can be created as
waitlisted - the waitlist mode used for that registration is stored in metadata
- a waitlist email is queued
If the event is paid, the effective waitlist behavior changes:
- paid registrations are forced into
offeredmode in the public flow
This is true even if the event itself is configured as manual or automatic.
How Each Waitlist Mode Behaves
Manual mode
Manual means the system will collect waitlisted registrations, but staff controls the next step.
What this means in practice:
- full-event signups can still join the waitlist
- the person stays
waitlisted - the system does not auto-promote the next person
- staff can decide when to create an offer or, for free registrations, manually confirm the next person
This is a strong fit when the team wants human review before a seat is released.
Example:
A cultivation dinner may have sponsor seats, board seats, and guest holds that staff wants to reconcile before offering the next spot.
Offered mode
Offered means the next person gets a time-limited opportunity to claim the seat.
What this means in practice:
- the registrant remains
waitlisted - an offer expiry is stored on the registration
- a signed public offer URL can be generated
- the claimant must use the same email address used to join the waitlist
- if the offer expires or was already claimed, the claim flow fails cleanly
This is the safest waitlist pattern for paid events because it keeps payment and seat release tied together.
Example:
A paid luncheon sells out. The next person on the waitlist receives an offer and can complete checkout only if the offer is still active.
Automatic mode
Automatic means the system promotes the oldest eligible waitlisted registration when a seat becomes available.
What this means in practice:
- the event must have waitlisting enabled
- the event must be in
automaticmode - the event must have capacity greater than
0 - the oldest waitlisted registration is chosen first
- a short lock is used to reduce duplicate promotion under busy conditions
Automatic mode behaves differently for free and paid registrations.
Free automatic promotion
For a free registration, the next person is:
- moved from
waitlistedtoconfirmed - given a
confirmed_attimestamp - sent a confirmation email
Paid automatic promotion
For a paid registration, the next person is:
- moved from
waitlistedtopending - not yet confirmed
- sent a promotion email so they can complete payment
This is a key operational distinction:
- automatic does not mean "free seat instantly confirmed for every case"
- for paid registrations, it means "moved into an active checkout/payment state"
How Paid and Manual Workflows Differ
Paid events behave more conservatively because a seat should not be fully given away until payment is addressed.
That is why the public flow forces paid waitlist registrations into offer-based handling.
Operationally, that means:
- a paid full-event signup joins the waitlist
- the system stores the pricing snapshot with the waitlist registration
- if an offer is active, the registrant can open a signed offer page
- the same email address must be used to claim it
- if the amount is still positive, the registrant moves into payment handling
For free waitlisted registrations, staff has more flexibility:
- they can be auto-confirmed in automatic mode
- they can be manually promoted from the registrations table
How Seats Open Back Up
A seat can become available when an active seat holder no longer reserves capacity.
Confirmed triggers in the audited implementation include:
- a confirmed registration being refunded
- a registration status changing to
cancelledorrefundedthrough the status service - stale pending registrations or expired offers being cleaned up by the stale-registration command
When this happens, the next result depends on the event's mode.
What Staff Can Do From the Dashboard
The dashboard gives staff two different levels of control.
Manage Waitlist page
This page is useful when staff wants a clean queue view of only waitlisted registrations.
It supports:
- seeing who is currently waitlisted
- seeing whether an offer is active
- creating or refreshing an offer
- expiring an offer
Registrations table
This is where staff gets more operational control.
Confirmed actions include:
- resending waitlist emails
- resending offer emails
- expiring or revoking offers
- manually promoting free registrations
This table is also where staff can later handle confirmed registrations for attendance and check-in.
Recommended Scenarios for Each Mode
Use Manual for higher-touch events
Best for:
- donor cultivation dinners
- board events
- invitation-sensitive programs
- events where seat releases need staff review first
Why:
- staff stays in control
- no one moves forward without human review
Use Offered for paid or fairness-sensitive replacement
Best for:
- paid events
- events where seat release should include a clear claim window
- cases where you want the next person to act before the seat is given away
Why:
- it holds the seat temporarily
- it gives the next person a clean claim path
- it avoids immediate manual back-and-forth
Use Automatic for simpler operational flows
Best for:
- free events
- community events with straightforward capacity rules
- teams that want less manual intervention
Why:
- oldest eligible person moves forward automatically
- staff does not need to review every single seat release
Common Mistakes and Operational Risks
Staff often assume a newly opened seat is immediately available. That is not always true if there is already a pending registration or an active offer holding capacity.
Paid waitlist registrations should not be planned as if they will auto-confirm. The public flow forces them into offer-based handling.
If guests or ticket quantities are involved, capacity is based on seat units, not just the number of registrations.
For first-time setups, Manual is usually the safest mode unless the team already has a clear process for automatic or offer-based handling.
Notes
Note: The audited implementation confirms the event-level waitlist mode choices, the public offer claim flow, automatic promotion logic, the dedicated
Manage Waitlistpage, and the waitlist actions in the registrations table.
Note: The audited implementation also confirms that only
confirmedregistrations can be manually checked in. Waitlisted people do not bypass that rule.
TODO: If your team needs a tenant-facing explanation of exactly when automatic promotion jobs run in every payment-provider path, confirm with product or QA whether that should be documented more explicitly for staff.