Introduction

Bookings represent appointments and class reservations made on behalf of a client at a provider. The API supports two distinct booking flows — spa appointments and gym classes — each with its own request shape and scheduling rules.

What you can do

List class categories

List classes

Book spa services for a client

Book a class appointment for a client

Cancel a booking

List bookings for a client

Retrieve the status of a single booking

Key concepts

Spa vs class bookings

Spa and class bookings are separate flows with separate endpoints and required fields. Do not attempt to mix them.

Flow	Endpoint	What you provide
Spa appointment	`POST /bookings/spa`	Provider, service, slot, client details
Class booking	`POST /bookings/class`	Provider, class instance ID, client details

Spa bookings require a specific time slot obtained from the provider's availability endpoint. Class bookings require a class instance ID obtained from the provider's class schedule.

Booking lifecycle

Status	Meaning
`pending`	The booking was created and is awaiting provider confirmation
`confirmed`	The booking is active and the slot or class instance is reserved
`cancelled`	The booking has been cancelled; the slot is released
`completed`	The visit took place
`rescheduled`	The booking was moved; the original is closed and a new booking was created

Cancellation

Cancellation is irreversible. Once a booking is cancelled, the slot is released back to the provider and cannot be reclaimed via the API. If the client wants to visit at the same time, create a new booking — availability is not guaranteed.

The cancel endpoint is idempotent by design: cancelling an already-cancelled booking returns a permission_denied error with no side effects.

Idempotency

Always include an Idempotency-Key header on booking creation and rescheduling requests. Network timeouts on these endpoints can leave the booking state ambiguous — an idempotency key lets you retry safely and receive the original response if the request already succeeded.

Providers — retrieve available class instances before creating a booking

Co-pay — purchase a co-pay package if the users pass or credits don't cover a class appointment or spa service

Lookup — generate a lookup token to book a class or spa service

What you can do#

Key concepts#

Related sections#

What you can do

Key concepts

Related sections