> ## 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](https://docs.anny.co/developers/guides/json-api-conventions.md). For slot search, see [Availability & Booking Search](https://docs.anny.co/developers/guides/availability.md).

***

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

**Date picker flow**

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

**List flow**

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.

**Series flow**

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.

**1. Get waitlist start intervals**

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.

**2. Get waitlist end intervals**

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.