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.