Waitlist Form Mechanics: Capacity, Priority, and Promotion Workflow

A waitlist form is a short signup form attached to a state machine. Most of the engineering work is in the state machine, not the fields.

Every entry needs to resolve into one of six states:

waitlisted
offered
converted
declined
expired
closed

waitlisted is the default state when a submission arrives after capacity is full. Capacity itself should be counted by seats claimed, not by row count, so a party-size field matters as much as the email field.

Priority Is a Sort, Not a Debate

Priority order has to be a queryable value on each row, not something the team argues about when a seat opens:

priority_rank = f(timestamp, segment, party_size)

First come, first served sorts on timestamp alone. Segment priority (members before non-members) adds a tiebreaker column. Fit-based matching filters the queue down to entries where party_size <= seats_available before applying either sort. Whichever model you pick, it has to be computable, not remembered.

Promotion Needs an Expiry Clock

A promotion notification is a row transition, waitlisted -> offered, with two extra fields:

offered_at
expires_at

The cascade logic on expiry is what makes a waitlist self-healing:

if (now > row.expires_at && row.status === "offered") {
  row.status = "expired";
  promoteNext(row.queue_id);
}

Without that check running on a schedule, offered silently becomes a dead end.

Conversion Is the Metric That Matters

Track converted, declined, and expired counts per queue. If ten offers convert three, filling five seats takes roughly seventeen offers -- a number you can only get from state, not from a signup count.

The full field list, priority models, and promotion email structure are in the Waitlist Form Guide.

The state machine is the part you own as the developer. For the registration side -- capacity, reminder timing, and check-in operations -- see the Event Registration Form and Sign-Up Form Guide -- Capacity, Reminders, and Check-In.