> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Waitlist
Use waitlist only when a resource allows waitlist entries and the requested period is unavailable because it is fully booked.
For general request conventions, see [JSON:API Conventions](/developers/guides/json-api-conventions). For slot search, see [Availability & Booking Search](/developers/guides/availability).
***
## When To Display Waitlist
Show waitlist only when both conditions are true:
1. The resource has waitlist enabled.
2. The requested period is unavailable because it is `booked_out`.
In the shop frontend this is the concrete gate:
* `resource.metaSettings.waitlist.enabled === true`
* the unavailable interval or series has `unavailability_type === BOOKED_OUT`
Do not show waitlist for other unavailability reasons like lead time conflicts, off-schedule dates, or duration conflicts.
Show the generic waitlist CTA when:
* the resource enables waitlist
* at least one fetched start or end interval is `BOOKED_OUT`
Booked out calendar days are also used as direct waitlist entry points:
* the tooltip is shown only for booked out days
* clicking an unavailable day opens waitlist only for booked out days
Show a per-slot “Join waitlist” action only for intervals where:
* the resource enables waitlist
* `interval.unavailability_type === BOOKED_OUT`
If no valid period selection is available at all, the list view falls back to a generic waitlist CTA.
Show the waitlist CTA only when:
* the selected series is not available
* the selected series has `unavailability_type === BOOKED_OUT`
* the resource enables waitlist
***
## Auth Requirement
Creating, listing, and deleting waitlist spots requires an authenticated customer account.
* unauthenticated shop calls are skipped client-side
* backend create, list, and delete authorization rejects requests without an active customer
Public availability endpoints can still be used to decide whether waitlist should be offered.
***
## Waitlist Interval Requests
The waitlist step uses the same availability engine as booking search, but with the waitlist validation strategy.
Use this to fetch possible waitlist start points:
```http theme={null}
GET /api/v1/intervals/waitlist-start?service_id={service_id}&resource_id={resource_id}&date=2026-04-15&timezone=Europe/Berlin
```
| Parameter | Required | Notes |
| ------------- | -------- | ------------------------------------------------------------ |
| `service_id` | yes | Service id or uuid used to build service configuration |
| `resource_id` | no | Recommended when the waitlist belongs to a specific resource |
| `date` | no | Use `YYYY-MM-DD` for a single-day request |
| `start_date` | no | Optional pagination cursor in Atom format |
| `timezone` | no | Defaults to resource timezone or organization timezone |
| `duration` | no | Optional requested duration in the service unit |
If `date` is omitted, the backend falls back to paginated interval lookup based on `start_date` and service configuration.
Use this after the user picked a waitlist start:
```http theme={null}
GET /api/v1/intervals/waitlist-end?service_id={service_id}&resource_id={resource_id}&date_time=2026-04-15T09:00:00%2B02:00&timezone=Europe/Berlin
```
| Parameter | Required | Notes |
| ------------- | -------- | ------------------------------------------------ |
| `service_id` | yes | Service id or uuid |
| `date_time` | yes | Start datetime in Atom / ISO 8601 format |
| `resource_id` | no | Recommended for resource-specific waitlist flows |
| `timezone` | no | Defaults to resource or organization timezone |
| `adhoc` | no | Optional boolean |
***
## Create A Waitlist Spot
Create the actual waitlist entry with the authenticated customer API:
```http theme={null}
POST /api/v1/waitlist-spots
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: Bearer {customer_token}
```
```json theme={null}
{
"data": {
"type": "waitlist-spots",
"attributes": {
"start_date": "2026-04-15T09:00:00+02:00",
"end_date": "2026-04-15T11:00:00+02:00"
},
"relationships": {
"resource": {
"data": {
"type": "resources",
"id": "123"
}
},
"service": {
"data": {
"type": "services",
"id": "456"
}
}
}
}
}
```
### Required fields
| Location | Field | Required | Notes |
| ---------------------------------- | ------------------- | -------- | ----------------------------------------------------- |
| `data.type` | `waitlist-spots` | yes | Must match the JSON:API resource type |
| `data.attributes.start_date` | Atom datetime | yes | Preferred start |
| `data.attributes.end_date` | Atom datetime | yes | Preferred end |
| `data.relationships.resource.data` | resource identifier | yes | Required by validator and used to derive organization |
### Optional fields
| Location | Field | Required | Notes |
| --------------------------------- | ---------------------------- | -------- | ----------------------------------------------------------------------------- |
| `data.relationships.service.data` | service identifier or `null` | no | The sample backend request allows `null`, but the shop sends the main service |
### What the backend fills automatically
You do not send these values:
* `account_id` is taken from the authenticated customer
* `organization_id` is derived from the resource
* `uuid` is generated automatically
### Duplicate handling
If the same customer already has an active waitlist entry for the same resource, `start_date`, and `end_date`, the backend replaces the old row and keeps the same UUID.
***
## List And Remove Waitlist Spots
List current active waitlist entries for the authenticated customer:
```http theme={null}
GET /api/v1/waitlist-spots?with_position=true&filter[resource]=123
```
Notes:
* results include only active entries
* past entries are excluded
* entries already converted to bookings are excluded
* `with_position=true` adds `meta.position`
Delete an entry by waitlist UUID:
```http theme={null}
DELETE /api/v1/waitlist-spots/{waitlist_uuid}
```
Only the customer who owns the waitlist entry can delete it.