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

1. Your website posts an email address to
   [create a signup](/docs/api/waitlist/create).
2. 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.
3. We email them the confirmation, unless you switched that off.
4. 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.

:::note 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](/docs/api/waitlist/create) returns `waitlist_disabled`.

## Endpoints

|                                               |                                         |
| --------------------------------------------- | --------------------------------------- |
| [Create](/docs/api/waitlist/create)           | `POST /v1/waitlist/signups`             |
| [List](/docs/api/waitlist/list)               | `GET /v1/waitlist/signups`              |
| [Retrieve](/docs/api/waitlist/retrieve)       | `GET /v1/waitlist/signups/{id}`         |
| [Resend](/docs/api/waitlist/resend)           | `POST /v1/waitlist/signups/{id}/resend` |
| [Unsubscribe](/docs/api/waitlist/unsubscribe) | `DELETE /v1/waitlist/signups/{id}`      |

## The object

```json
{
    "id": "wl_7hqm4tzvbc82nkxrdp9sfjwe",
    "object": "waitlist_signup",
    "email": "jamie@example.com",
    "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.