Skip to main content
A group booking is one booking with capacity greater than 1: one supplier, one time, one place, and several clients. A class, a group lesson or a workshop is one group booking. Each client on it is a participant. This guide covers:
  • Create a booking with room for more than one client.
  • Register clients on it, and handle a full booking or a duplicate.
  • Pay for the seats, which the API leaves to you.
  • Check in participants at the door, and remove one who drops out.
Every route here takes the API key alone, so it runs on your server. There is no client-plane or supplier-plane route for participants.

Create a group booking

Create the booking with POST /bookings, as in Create a single booking, and send capacity. The example books a class of 8 at a venue:
  • The booking’s client takes the first seat. Every booking is created with its clientId already registered as a participant, so a new booking reads participantCount: 1. A class of 8 has 7 seats left.
  • capacity defaults to 1. Leave it out and the booking is one-to-one.
  • A converted hold or a package session is always one-to-one. POST /holds/{reservationId}/convert and the package-booking routes create every booking with capacity: 1. A package’s own capacity field doesn’t change that. Raise it afterwards with PATCH /bookings/{bookingId}. See Change the capacity.
The booking carries three fields for its seats:
Availability search doesn’t sell seats. Search finds free supplier time. A group booking occupies its supplier’s time like any other booking, so its empty seats never appear in POST /availability/search or POST /availability/suppliers. List your classes from your own records, and read capacity and participantCount from the booking.

How participants are funded

They aren’t. The API doesn’t charge for a seat. Here is exactly what it does:
  • The booking is funded once, when it’s created. Each service line draws quantity units (default 1) from its order item. capacity doesn’t change how much is drawn.
  • Registering a participant draws nothing. It writes the roster row and adds 1 to participantCount. It reads no order, draws no order item, uses no package credit and records no payment.
  • Removing a participant returns nothing, because nothing was drawn for them.
So deciding who has paid for a seat is your server’s job. Two ways fit what the API does:
  • One buyer pays for every seat. Create the order item with quantity equal to the seats, and book its service line with the same quantity. The line’s amount is the unit price times quantity. Then register the other clients for free.
  • Each participant pays for their own seat. Take each payment in your own system before you register the client. Keep the link between the payment and the participant yourself: the API has no field for it.

Register a participant

Register one client at a time:
Register a participant
201 Created
Take the clientId from your own records or from POST /clients/me on your server. Never trust one the browser sends. Capacity is enforced in the same write as the registration. Two requests for the last seat can’t both succeed. One gets 201. The other gets 409. Only a SCHEDULED or STARTED booking takes a registration. Any other status is refused, and nothing is written:

The booking is full

Registering past capacity is a 409, and nothing is written. There’s no waitlist: WAITLISTED and waitlistPosition exist in the schema, but nothing sets them.
Tell the client the class is full. To add a seat, raise capacity first.

The client is already registered

Registering a client who is on the booking is also a 409 CONFLICT. No second row is written.
This includes the booking’s own client, who is registered when the booking is created. A client you removed can be registered again. Registering them writes a fresh participant row, and they’re back on the roster. Both refusals share the code CONFLICT. Branch on the roster, not on message: if the client is in GET /bookings/{bookingId}/participants, it’s a duplicate; otherwise the booking is full. The message isn’t reliable for this: the capacity check runs first, so on a full booking a duplicate also gets “is at capacity”.

Other refusals

Show the roster

List participants
data is every registered participant, with their check-in state.
  • It isn’t paginated. The roster is bounded by capacity.
  • Removed participants are left out.
  • It’s ordered by clientId, not by when each client registered. Sort by registeredAt if order matters.
  • An unknown bookingId isn’t an error. It returns 200 with data: []. An empty roster doesn’t confirm the booking exists.
GET /bookings/{bookingId}/participants/{clientId} reads one participant. It’s a 404 NOT_FOUND, “Participant not found”, when the client isn’t registered or was removed. A supplier sees the roster of their own booking in GET /suppliers/me/bookings/{bookingId}, on the supplier plane. See Supplier portal: bookings.

Check in a participant

Check a participant in when they arrive:
Check in
200 returns the participant with checkInStatus: "CHECKED_IN" and checkInAt set to now.
  • It’s safe to retry. Checking in someone already checked in leaves them checked in, and returns them with the first checkInAt. A retry doesn’t move it.
  • It doesn’t change the booking. The booking’s status stays as it is. Attendance for the booking as a whole is the supplier’s report. See Supplier day view and attendance reports.
  • There’s no undo. No route sets checkInStatus back to PENDING, and none sets NO_SHOW.
  • It works until the booking is settled. A SCHEDULED, STARTED or AWAITING_CONFIRMATION booking takes a check-in, so you can finish the door list after the session ends. A settled, disputed or cancelled booking doesn’t:
A participant who isn’t registered, or was removed, is a 404. So is a booking that doesn’t exist, with “Booking bk_… not found”:

Check in from a supplier’s portal

The supplier plane has no check-in route. If the supplier checks clients in from your portal, your server does it for them with the key:
  1. Read GET /suppliers/me/bookings/{bookingId} with the supplier’s token. A 404 means it isn’t their booking. Stop there.
  2. Call check-in with the API key.
The key acts for the business, so step 1 is the only thing stopping a supplier checking in clients on someone else’s booking.

Remove a participant

Remove a participant
204 with no body. The seat is free again, and participantCount goes down by 1.
  • The booking stays scheduled for everyone else. To call off the whole class, cancel the booking with POST /bookings/{bookingId}/status. See Cancel or reschedule a booking.
  • It refunds nothing. No money or credit was taken for the seat. If you took a payment in your own system, return it there.
  • The booking’s own client can be removed too. The booking’s clientId doesn’t change.
A participant who isn’t registered, or was already removed, is a 404 NOT_FOUND with the message “Participant cli_… not found on this booking”.

Change the capacity

Send a new capacity with PATCH /bookings/{bookingId}:
isGroupBooking follows it. Lowering capacity below participantCount is accepted and removes nobody. New registrations are refused until enough participants are removed.

Reference

Endpoints used in this guide

Errors and edge cases

See Errors for the envelope and every code.