Invitation Codes

Create invite-only waitlists with gated access using invitation codes.

Advanced Plan Required Invitation codes require an Advanced plan or higher.

Invitation codes let you create invite-only waitlists where signups must provide a valid code to join. This is useful for gated launches, exclusive beta programs, or partner-only access.

How It Works

Enable require_invitation_code on your waitlist
Create one or more invitation codes with optional usage limits
Share codes with the people you want to invite
When someone signs up, they must provide a valid code or the signup is rejected

Enable Invitation Codes

Enable the invitation code requirement by updating your waitlist settings:

PATCH /waitlists/{waitlist_id}
{
  "settings": {
    "require_invitation_code": true
  }
}

When enabled, the signup form displays an “Invitation Code” field that must be filled in. Signups without a valid code receive a 403 error.

Create a Code

API: POST /waitlists/{waitlist_id}/codes

{
  "code": "BETA-2025",
  "max_uses": 100
}

Field	Type	Required	Description
`code`	string (3-50 characters)	No	The invitation code string. May contain letters, numbers, hyphens, and underscores. If omitted, a random 12-character hex code is generated.
`max_uses`	integer (0-1,000,000)	No	Maximum number of times this code can be used. `0` or omitted means unlimited.

Response (201):

{
  "code": "BETA-2025",
  "max_uses": 100,
  "uses": 0,
  "created_at": "2025-03-15T10:30:00.000Z"
}

If you don't provide a code value, a random 12-character hex string is generated automatically.

List Codes

API: GET /waitlists/{waitlist_id}/codes

Returns all invitation codes for the waitlist with their current usage:

{
  "codes": [
    {
      "code": "BETA-2025",
      "max_uses": 100,
      "uses": 42,
      "created_at": "2025-03-15T10:30:00.000Z"
    },
    {
      "code": "VIP-ACCESS",
      "max_uses": 0,
      "uses": 7,
      "created_at": "2025-03-16T08:00:00.000Z"
    }
  ]
}

Delete a Code

API: DELETE /waitlists/{waitlist_id}/codes/{code}

Returns 204 No Content on success. Existing signups that used this code are not affected.

Signing Up with a Code

When require_invitation_code is enabled, the signup request must include an invitation_code field:

POST /public/waitlists/{waitlist_id}/signups
{
  "email": "user@example.com",
  "invitation_code": "BETA-2025"
}

The system validates the code before creating the signup. If the code is invalid or has reached its usage limit, the signup is rejected.

On the hosted signup page and embed widget, the invitation code field appears automatically when the waitlist requires it.

Usage Tracking

Each code tracks how many times it has been used:

Field	Description
`uses`	Number of signups that have used this code
`max_uses`	Maximum allowed uses (`0` = unlimited)

When max_uses is set and uses reaches that limit, the code is automatically rejected on future signup attempts.

Example: Full Workflow

1. Enable invitation codes on your waitlist:

PATCH /waitlists/a1b2c3d4
{
  "settings": {
    "require_invitation_code": true
  }
}

2. Create a code with a 50-use limit:

POST /waitlists/a1b2c3d4/codes
{
  "code": "LAUNCH-DAY",
  "max_uses": 50
}

3. Share the code with your invitees. They sign up with it:

POST /public/waitlists/a1b2c3d4/signups
{
  "email": "invited@example.com",
  "invitation_code": "LAUNCH-DAY"
}

4. Check usage:

GET /waitlists/a1b2c3d4/codes

Creating Waitlists — configure waitlist settings including invitation code requirements
Signup Form — how the public signup form works
Security — authentication and data protection

Previous Bulk Delete Next Reward Actions