# Leave the waitlist

> The checkout.hosted.leave_waitlist operation: POST /api/v1/public/checkout_sessions/{sessionId}/waitlist/leave in the REST API and the checkout_hosted_leave_waitlist tool in the MCP server.

Takes a customer off the brand's waitlist with the link from the waitlist's emails (the confirmation and the
one saying the brand can sell): the entry is never notified, and a pending one can't be confirmed any more.
The token is the proof: no session key is needed. Leaving twice changes nothing. Joining again later starts a
new double opt-in (spec §23).

Public: the hosted page calls it when the customer confirms with a button, never on page load.

## At a glance

- **REST:** `POST /api/v1/public/checkout_sessions/{sessionId}/waitlist/leave`
- **MCP tool:** `checkout_hosted_leave_waitlist`
- **Operation ID:** `checkout.hosted.leave_waitlist`
- **Scope:** Brand
- **Permission:** `checkout:write`
- **Risk tier:** `write`
- **Dry run:** Not supported
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** None (a public endpoint, rate-limited per IP address)
- **Since:** M7

## Request

### Path parameters

| Field       | Type      | Description                         |
| ----------- | --------- | ----------------------------------- |
| `sessionId` | `cs_…` ID | The checkout session's ID (`cs_…`). |

### Body

A JSON object (`Content-Type: application/json`):

| Field   | Type      | Required | Description                                |
| ------- | --------- | -------- | ------------------------------------------ |
| `entry` | `wl_…` ID | Yes      | The waitlist entry (`wl_…`) from the link. |
| `token` | string    | Yes      | The token from the link.                   |

## Response

`200 OK` with a JSON object:

| Field         | Type                   | Description                                                                        |
| ------------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `object`      | `"waitlist_departure"` |                                                                                    |
| `status`      | `"left"`               |                                                                                    |
| `brandName`   | string                 |                                                                                    |
| `country`     | string                 |                                                                                    |
| `countryName` | string                 |                                                                                    |
| `leftAt`      | date-time              | When the customer left the waitlist (the first time, if they used the link twice). |

## Examples

### Leave from the email

```http
POST /api/v1/public/checkout_sessions/cs_01m4tx5nj8emwbyf7y9vcf48aa/waitlist/leave
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "entry": "wl_01m4tx5nj8emwbyf7y9vcf48ah",
  "token": "Qm9vdF9sZWF2ZV90b2tlbl9leGFtcGxlXzAwMDAwMDA"
}
```

Response (`200`):

```json
{
  "object": "waitlist_departure",
  "status": "left",
  "brandName": "Genno",
  "country": "GB",
  "countryName": "United Kingdom",
  "leftAt": "2026-10-19T09:30:00.000Z"
}
```

## Errors

| Code                                                                                           | HTTP status | When                                                                                      | What to do                                                                                                                          |
| ---------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)       | 404         | No such checkout session.                                                                 | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                |
| [`waitlist_link_invalid`](https://ownrecord.io/docs/reference/errors.md#waitlist_link_invalid) | 400         | The link's entry or token is wrong, or the entry doesn't belong to this checkout session. | Use the link exactly as it is in the email. The checkout link works only after the email saying the brand can sell in your country. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`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).