API reference · Bookings

Bookings and waitlist

Create and cancel bookings through ClassFlow’s booking authority, then read booking and waitlist state.

Endpoints6

Primary objectBookingObject

Tenant boundaryCredential studio

GET/bookings

List bookings

Lists bookings filtered by class, member, or status.

Required scope: bookings:read
Success: 200
Response: Page<BookingObject>

Parameters

class_idquery

uuid

Return bookings for one class.

member_idquery

uuid

Return bookings for one member.

statusquery

string

Filter by booking status.

cursorquery

uuid

Opaque cursor returned by the previous page. Pass it back unchanged.

limitquery

integer

Number of records to return. Defaults to 50; maximum 200.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/bookings" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "object": "list",
  "data": [{
    "id": "bf4a8333-cce8-4d1c-922d-7585317af831",
    "object": "booking",
    "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
    "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
    "status": "confirmed",
    "booking_source": "partner_api",
    "created_at": "2026-08-02T20:51:00Z"
  }],
  "has_more": false,
  "next_cursor": null
}

POST/bookings

Create a booking

Runs the canonical booking flow, including capacity, eligibility, spot, and waitlist rules.

Required scope: bookings:write
Success: 201
Response: BookingObject

Parameters

Idempotency-Keyheaderrequired

string

Unique key for this write. Results are replayable for 24 hours.

Request body

Send a JSON object matching PartnerBookingCreate.

application/json

{
  "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
  "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
  "join_waitlist": true
}

Example request

curl -X POST "https://api.getclassflow.com/partner/v1/bookings" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-$(uuidgen)" \
  --data '{
  "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
  "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
  "join_waitlist": true
}'

Example response

201 · application/json

{
  "id": "bf4a8333-cce8-4d1c-922d-7585317af831",
  "object": "booking",
  "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
  "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
  "status": "confirmed",
  "booking_source": "partner_api",
  "created_at": "2026-08-02T20:51:00Z"
}

GET/bookings/{booking_id}

Retrieve a booking

Returns one booking when its class is in a permitted location.

Required scope: bookings:read
Success: 200
Response: BookingObject

Parameters

booking_idpathrequired

uuid

The stable ClassFlow identifier for the booking.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/bookings/YOUR_BOOKING_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "id": "bf4a8333-cce8-4d1c-922d-7585317af831",
  "object": "booking",
  "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
  "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
  "status": "confirmed",
  "booking_source": "partner_api",
  "created_at": "2026-08-02T20:51:00Z"
}

DELETE/bookings/{booking_id}

Cancel a booking

Cancels a booking through the canonical cancellation policy and side-effect flow.

Required scope: bookings:write
Success: 200
Response: BookingObject

Parameters

booking_idpathrequired

uuid

The stable ClassFlow identifier for the booking.

reasonquery

string

Optional cancellation reason, up to 500 characters.

Idempotency-Keyheaderrequired

string

Unique key for this write. Results are replayable for 24 hours.

Example request

curl -X DELETE "https://api.getclassflow.com/partner/v1/bookings/YOUR_BOOKING_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Idempotency-Key: booking-$(uuidgen)"

Example response

200 · application/json

{
  "id": "bf4a8333-cce8-4d1c-922d-7585317af831",
  "object": "booking",
  "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
  "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
  "status": "confirmed",
  "booking_source": "partner_api",
  "created_at": "2026-08-02T20:51:00Z"
}

GET/waitlist

List waitlist entries

Lists waitlist entries filtered by class, member, or status.

Required scope: bookings:read
Success: 200
Response: Page<WaitlistObject>

Parameters

class_idquery

uuid

Return entries for one class.

member_idquery

uuid

Return entries for one member.

statusquery

string

Filter by waitlist status.

cursorquery

uuid

Opaque cursor returned by the previous page. Pass it back unchanged.

limitquery

integer

Number of records to return. Defaults to 50; maximum 200.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/waitlist" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "object": "list",
  "data": [{
    "id": "3417c872-0469-4059-994a-26b3e53eed03",
    "object": "waitlist",
    "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
    "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
    "position": 2,
    "status": "waiting",
    "converted_to_booking": false
  }],
  "has_more": false,
  "next_cursor": null
}

GET/waitlist/{waitlist_id}

Retrieve a waitlist entry

Returns position, status, and booking-conversion state for one entry.

Required scope: bookings:read
Success: 200
Response: WaitlistObject

Parameters

waitlist_idpathrequired

uuid

The stable ClassFlow identifier for the waitlist entry.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/waitlist/YOUR_WAITLIST_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "id": "3417c872-0469-4059-994a-26b3e53eed03",
  "object": "waitlist",
  "class_id": "70bf3848-d688-40cf-9692-6283c6652bb3",
  "member_id": "5fef0f5c-2165-48e0-a730-9c066eb37f9a",
  "position": 2,
  "status": "waiting",
  "converted_to_booking": false
}

Object schema

BookingObject

Full OpenAPI schema

iduuid

Stable booking identifier.

class_iduuid

Booked class session.

member_iduuid

Booked member.

statusstring

Confirmed, cancelled, or other canonical booking state.

class_spot_iduuid | null

Selected spot when the class requires spot selection.

waitlist_positioninteger | null

Position when the request joins the waitlist.