# List waitlist entries

> The waitlist.entries.list operation: GET /api/v1/waitlist_entries in the REST API and the waitlist_entries_list tool in the MCP server.

Lists the brand's waitlist in the mode of the request, newest first: customers who asked to be told when the
brand can sell in their country (spec §23), with what they wanted to buy and its value. `status: pending`
entries haven't confirmed their email yet. Filter by `country` or `status`; page with `limit` and
`starting_after`. Emails are customer data: show them only to people who need them.

## At a glance

- **REST:** `GET /api/v1/waitlist_entries`
- **MCP tool:** `waitlist_entries_list`
- **Operation ID:** `waitlist.entries.list`
- **Scope:** Brand
- **Permission:** `waitlist:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `waitlist:read` scope
- **Since:** M4

## Request

### Query parameters

| Field            | Type                          | Required | Description                             |
| ---------------- | ----------------------------- | -------- | --------------------------------------- |
| `limit`          | integer (1 to 100)            | No       |                                         |
| `starting_after` | `wl_…` ID                     | No       |                                         |
| `country`        | string                        | No       | Only entries for this country.          |
| `status`         | one of `pending`, `confirmed` | No       | Only pending or only confirmed entries. |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                        | Type                                                                                                                                                      | Description                                                                              |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `data`                       | array of object                                                                                                                                           |                                                                                          |
| `data[].id`                  | `wl_…` ID                                                                                                                                                 |                                                                                          |
| `data[].object`              | `"waitlist_entry"`                                                                                                                                        |                                                                                          |
| `data[].livemode`            | boolean                                                                                                                                                   |                                                                                          |
| `data[].entityId`            | `ent_…` ID                                                                                                                                                |                                                                                          |
| `data[].brandId`             | `brd_…` ID                                                                                                                                                |                                                                                          |
| `data[].email`               | string                                                                                                                                                    |                                                                                          |
| `data[].country`             | string                                                                                                                                                    |                                                                                          |
| `data[].subdivision`         | string or null                                                                                                                                            |                                                                                          |
| `data[].customerType`        | one of `b2c`, `b2b`                                                                                                                                       |                                                                                          |
| `data[].productIds`          | array of string                                                                                                                                           |                                                                                          |
| `data[].priceIds`            | array of string                                                                                                                                           |                                                                                          |
| `data[].estimatedValue`      | money                                                                                                                                                     |                                                                                          |
| `data[].source`              | one of `checkout`, `api`                                                                                                                                  |                                                                                          |
| `data[].status`              | one of `pending`, `confirmed`                                                                                                                             |                                                                                          |
| `data[].consent`             | object                                                                                                                                                    |                                                                                          |
| `data[].consent.text`        | string                                                                                                                                                    |                                                                                          |
| `data[].consent.textVersion` | string                                                                                                                                                    |                                                                                          |
| `data[].consent.at`          | date-time                                                                                                                                                 |                                                                                          |
| `data[].confirmedAt`         | date-time or null                                                                                                                                         |                                                                                          |
| `data[].checkoutSessionId`   | `cs_…` ID or null                                                                                                                                         |                                                                                          |
| `data[].regimeId`            | string or null                                                                                                                                            |                                                                                          |
| `data[].blockedReason`       | one of `evidence_conflict`, `unsupported_tax_category`, `registration_required`, `rate_unavailable`, `jurisdiction_blocked`, `tax_id_unavailable` or null |                                                                                          |
| `data[].notifiedAt`          | date-time or null                                                                                                                                         |                                                                                          |
| `data[].unsubscribedAt`      | date-time or null                                                                                                                                         | When the customer left the waitlist (the link in its emails); never notified after that. |
| `data[].createdAt`           | date-time                                                                                                                                                 |                                                                                          |
| `has_more`                   | boolean                                                                                                                                                   |                                                                                          |
| `next_cursor`                | string or null                                                                                                                                            |                                                                                          |

## Examples

### Confirmed entries for the UK

```http
GET /api/v1/waitlist_entries?country=GB&status=confirmed
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "data": [
    {
      "id": "wl_01m4tx5nj8emwbyf7y9vcf48ah",
      "object": "waitlist_entry",
      "livemode": false,
      "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "email": "oliver@example.com",
      "country": "GB",
      "subdivision": null,
      "customerType": "b2c",
      "productIds": ["prod_01m4tx5nj8emwbyf7y9vcf48ae"],
      "priceIds": ["price_01m4tx5nj8emwbyf7y9vcf48ad"],
      "estimatedValue": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "source": "checkout",
      "status": "confirmed",
      "consent": {
        "text": "Notify me when Genno can sell in United Kingdom",
        "textVersion": "2026-10-14",
        "at": "2026-10-14T10:00:00.000Z"
      },
      "confirmedAt": "2026-10-14T10:12:00.000Z",
      "checkoutSessionId": "cs_01m4tx5nj8emwbyf7y9vcf48aa",
      "regimeId": null,
      "blockedReason": "registration_required",
      "notifiedAt": null,
      "unsubscribedAt": null,
      "createdAt": "2026-10-14T10:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                   | HTTP status | When                                      | What to do                                                            |
| -------------------------------------------------------------------------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter is malformed (`param` names it). | Fix the fields listed in `details.issues` and send the request again. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).