# Confirm a waitlist sign-up

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

Confirms a waitlist entry with the token from its email (double opt-in, spec §23). The token is the proof: no
session key is needed. Only the latest link sent works, for 7 days; confirming twice changes nothing.

## At a glance

- **REST:** `POST /api/v1/public/checkout_sessions/{sessionId}/waitlist/confirm`
- **MCP tool:** `checkout_hosted_confirm_waitlist`
- **Operation ID:** `checkout.hosted.confirm_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:** M4

## 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 confirmation link. |
| `token` | string    | Yes      | The token from the confirmation link.                   |

## Response

`200 OK` with a JSON object:

| Field         | Type          | Description |
| ------------- | ------------- | ----------- |
| `status`      | `"confirmed"` |             |
| `brandName`   | string        |             |
| `country`     | string        |             |
| `countryName` | string        |             |

## Examples

### Confirm from the email

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

{
  "entry": "wl_01m4tx5nj8emwbyf7y9vcf48ah",
  "token": "q9VhN3bXk2mR7tY4wP8sZ1cL6fJ0dG5aE-uB_nH3oKx"
}
```

Response (`200`):

```json
{
  "status": "confirmed",
  "brandName": "Genno",
  "country": "GB",
  "countryName": "United Kingdom"
}
```

## 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_confirmation_invalid`](https://ownrecord.io/docs/reference/errors.md#waitlist_confirmation_invalid) | 400         | The link's entry or token is wrong, superseded by a newer email or older than 7 days, or the customer left the waitlist. | Links work for 7 days and only the latest one sent works. Join the waitlist again to get a new email. |

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).