Guide

Build a booking and waitlist flow

Read the studio schedule, identify the member, create one idempotent booking, and reflect the authoritative booking or waitlist result.

1. Read availability

GET

/classes?starts_after=2026-08-05T00:00:00Z
  &starts_before=2026-08-12T00:00:00Z
  &location_id=159e78c2-d0b4-44fc-995f-e0d587b42f55

Use available_count for display, but let the booking write re-check capacity. Availability can change between the read and write.

2. Identify the member

Use an existing member ID from your trusted mapping, or create a member with POST /members. Do not create a second member for every booking attempt.

3. Create the booking

POST /bookings

curl -X POST "$CLASSFLOW_API_URL/bookings" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Idempotency-Key: booking-3c68151a-9e55-4fd0-b3ae-1f111713fa32" \
  -H "Content-Type: application/json" \
  --data '{
    "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
    "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
    "join_waitlist": true
  }'

4. Handle waitlist state

When join_waitlist is true and the class cannot confirm a booking, the result can include waitlist state. Read GET /waitlist or subscribe to waitlist.updated and booking.created.

5. Cancel safely

Call DELETE /bookings/{booking_id} with a new idempotency key for the cancellation operation. ClassFlow applies the current cancellation policy and records the result.