The waitlist is for the people who want to hear the moment you open. They leave an email address on your marketing site, and what happens next is entirely your call: nothing, a confirmation email, or a confirmation email carrying a discount code they can use on their first purchase.

The flow

Your website posts an email address to create a signup.
If you configured a reward, we mint or look up the code and put it in the response, so you can show it on the page straight away.
We email them the confirmation, unless you switched that off.
When they register with the same address after you launch, the signup flips to converted and their personal code is locked to their account.

What the code can be

You pick this in your dashboard under Waitlist -> Settings, and the API follows whatever is set there. There is nothing to send per request.

Mode	What everyone gets
No code	Only the confirmation that they are on the list
One shared code	The same coupon code for everybody, picked from your coupons
A personal code	Their own single-use coupon, minted at signup

A personal code is an ordinary coupon: it shows up under Coupons, it is redeemed at checkout like any other, and it counts against the same reporting.

An incomplete setup still accepts signups

If the reward is switched on but not finished, for example unique without a discount value, the signup still succeeds and reward_code comes back null. Someone who left their email address should not be turned away over a half-filled settings screen.

Before you start

The waitlist is closed by default. Open it under Waitlist -> Settings, where you also choose the confirmation email and the reward. While it is closed, create returns waitlist_disabled.

Endpoints


Create	`POST /v1/waitlist/signups`
List	`GET /v1/waitlist/signups`
Retrieve	`GET /v1/waitlist/signups/{id}`
Resend	`POST /v1/waitlist/signups/{id}/resend`
Unsubscribe	`DELETE /v1/waitlist/signups/{id}`

The object

{
    "id": "wl_7hqm4tzvbc82nkxrdp9sfjwe",
    "object": "waitlist_signup",
    "email": "[email protected]",
    "name": "Jamie",
    "status": "pending",
    "reward_code": "LAUNCH-K4M9XR2P",
    "source": "api",
    "metadata": { "utm_source": "launch-page" },
    "created_at": "2026-08-03T17:44:13+00:00",
    "notified_at": null,
    "converted_at": null,
    "unsubscribed_at": null,
    "last_sent_at": "2026-08-03T17:44:13+00:00"
}

Field	Description
`id`	Use this in every other endpoint
`status`	`pending`, `notified`, `converted` or `unsubscribed`
`reward_code`	The discount code they were given, or `null`
`source`	`api` or `admin`
`metadata`	Whatever you sent, returned unchanged
`converted_at`	Set when someone registers with this address

Unlike an affiliate claim code, reward_code is returned on every response. It is a discount, not a credential: it is already in their inbox, it is worth one purchase, and a marketing page has to be able to show it again.

Waitlist overview

The flow

What the code can be

Before you start

Endpoints

The object