Subscribers & Referrals

Signup Lifecycle

When a user submits their email, they enter the signup lifecycle. There are two main states:

• Pending: If "Double Opt-In" is enabled in your project settings, new signups start as Pending. They receive a verification email and must click the link to confirm.
• Confirmed: The user is verified and officially on the waitlist. Only confirmed users count towards your plan limits and appear on the leaderboard.

Referral System

Viral growth is built-in. Every subscriber gets a unique referralCode immediately upon signing up.

How Attribution Works

1. User A signs up and gets code ABC123.
2. User A shares their link: https://your-site.com?ref=ABC123.
3. User B visits the link. The API/form captures the ref parameter.
4. When User B submits their email, the system records referred_by: User A.
5. Once User B is Confirmed, User A's referralCount increments by 1.

Queue Positions

WaitlistPilot calculates a "Queue Position" for every subscriber to gamify the experience. The position is dynamic and can change based on referrals.

The default logic prioritizes users with more referrals first, and then uses signup date as a tie-breaker (First-In-First-Out).

"If I invite 5 friends, I jump ahead of someone who signed up before me but invited no one."