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.
Create a group booking
Create the booking withPOST /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
clientIdalready registered as a participant, so a new booking readsparticipantCount: 1. A class of 8 has 7 seats left. capacitydefaults 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}/convertand the package-booking routes create every booking withcapacity: 1. A package’s owncapacityfield doesn’t change that. Raise it afterwards withPATCH /bookings/{bookingId}. See Change the capacity.
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
quantityunits (default 1) from its order item.capacitydoesn’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.
- One buyer pays for every seat. Create the order item with
quantityequal to the seats, and book its service line with the samequantity. The line’s amount is the unit price timesquantity. 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
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 pastcapacity is a 409, and nothing is written. There’s no
waitlist: WAITLISTED and waitlistPosition exist in the schema, but nothing
sets them.
capacity first.
The client is already registered
Registering a client who is on the booking is also a409 CONFLICT. No second
row is written.
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 byregisteredAtif order matters. - An unknown
bookingIdisn’t an error. It returns200withdata: []. 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
statusstays 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
checkInStatusback toPENDING, and none setsNO_SHOW. - It works until the booking is settled. A
SCHEDULED,STARTEDorAWAITING_CONFIRMATIONbooking takes a check-in, so you can finish the door list after the session ends. A settled, disputed or cancelled booking doesn’t:
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:- Read
GET /suppliers/me/bookings/{bookingId}with the supplier’s token. A404means it isn’t their booking. Stop there. - Call check-in with the API key.
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
clientIddoesn’t change.
404 NOT_FOUND with the message “Participant cli_… not found on this booking”.
Change the capacity
Send a newcapacity 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.