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. For slot search, see Availability & Booking Search.

When To Display Waitlist

Show waitlist only when both conditions are true:

The resource has waitlist enabled.
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.

Get waitlist start intervals

Use this to fetch possible waitlist start points:

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.

Get waitlist end intervals

Use this after the user picked a waitlist start:

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:

POST /api/v1/waitlist-spots
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: Bearer {customer_token}

{
  "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 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:

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:

DELETE /api/v1/waitlist-spots/{waitlist_uuid}

Only the customer who owns the waitlist entry can delete it.

Webhooks & Events