Book classes and appointments

Use this guide to book a client into classes and appointments, cancel a booking, and read a booking status. For how appointments, services and slots relate, see Data model and terminology.

Book classes

1. Find the client and list their client class passes.
2. Find the classes and check their booking windows and available capacity.
3. For a class with assigned places, list /classes/{id}/spots/ to obtain a spot_id.
4. Submit the client, pass and class identifiers to /bookings/.

For example, this request books one class and lets bsport assign a place. Replace the example IDs with values returned for your company, and YOUR_ENV_DOMAIN with public.staging.bsport.io (staging) or public.production.bsport.io (production). See Environments.

curl -X POST 'https://YOUR_ENV_DOMAIN/api/v2/management/bookings/' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Client-ID: YOUR_CLIENT_ID' \
  -H 'X-Company-ID: YOUR_COMPANY_ID' \
  -H 'Content-Type: application/json' \
  -d '{"client_id":123,"client_class_pass_id":456,"class_ids":[789],"should_auto_assign_spot":true}'

A 201 response contains a bookings array. The same pass, spot_id and options apply to every entry in class_ids. Use separate requests when different classes need different places. A validation failure rolls back the requested bookings and credit changes; a failure after creation, including a lost response, does not prove that nothing was booked. Query the client's bookings before deciding to repeat a write.

Booking list and detail responses include company_id, taken from the company that owns the class. Access checks use the same ownership, including for historical bookings.

should_keep_credits=true creates the booking without deducting pass credits. The default is false. should_notify_client defaults to true.

Cancel a booking

POST /bookings/{id}/cancel/ accepts an omitted body. For this manager operation, both options default to false: cancellation does not force a credit refund or send the cancellation notification. Set should_force_refund=true to refund consumed credits, and should_force_notify=true to request the cancellation notification. A credit refund is not a refund of the purchase price.

Interpret booking status

The response and query filter use different representations of the same status.

Response booking_status_code	Query booking_status_code
OK	0
Canceled by manager	1
Canceled by client	2
Class canceled	3

spot_information is display metadata, not the identifier to submit when booking. It can be empty or null. Its display fields include name, shape, prefix, suffix, fill, stroke and numeric indexType; use spot_id to select a place.

Book an appointment

A slot describes a duration and a credit cost, not a free time on the calendar, and V2 has no availability search. See Appointments, appointment services, and appointment slots for how the three resources relate.

Choose an appointment_slot_id, client_id and starts_at. An example request body is:

{"client_id":123,"appointment_slot_id":456,"starts_at":"2026-11-10T10:00:00+01:00"}

Submit it to POST /api/v2/management/appointments/ with the same authentication and JSON headers as the class-booking example. If the service has several teachers or venues, supply the corresponding teacher_id or venue_id. The service response does not expose these associations; confirm the service configuration with the company before booking. A service with one eligible teacher or venue selects it automatically.

The request cannot choose a client appointment pass. bsport selects the compatible pass with the earliest expiration date, then the lowest ID if expiration dates tie. No compatible pass or insufficient credits prevents creation. Use the returned appointment ID for subsequent reads or cancellation; cancellation refunds the booking credits.

How appointments, services and slots relate

Color and shape show what kind of resource a box is. Teal rectangles are set up by the studio, purple pills are held by a client, amber rounded boxes are records of something that happened, and the grey hexagon is the client. A solid arrow starts at the resource that holds an ID and ends at the resource the ID refers to. A dotted arrow is a relationship without an ID field.

%%{init: {"flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 60, "padding": 14}}}%%
flowchart LR
    appointment("<b>Appointment</b><br/>/appointments/<br/>One booking for one client")
    service["<b>Appointment service</b><br/>/appointment-services/<br/>The offering"]
    slot["<b>Appointment slot</b><br/>/appointment-slots/<br/>One duration and credit price"]
    appointment -->|"appointment_service_id"| service
    service -->|"appointment_slot_ids"| slot
    appointment -->|"appointment_slot_id"| slot
    class appointment record
    class service,slot definition
    classDef definition fill:#beede5,stroke:#21837d,stroke-width:2px,color:#0f3d39
    classDef held fill:#ece4f8,stroke:#6b4fa3,stroke-width:2px,color:#35205f
    classDef record fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#5e2a0c
    classDef person fill:#e5eaea,stroke:#565e5d,stroke-width:2px,color:#1e2323
    linkStyle default stroke-width:1.5px

Which pass pays for a booking

A client pass holds the credits a client has left. The colors and arrows are the same as in the previous diagram.

%%{init: {"flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 60, "padding": 14}}}%%
flowchart LR
    subgraph groupClasses ["Group classes"]
        direction LR
        classPass["<div style='width:240px'><b>Class pass</b><br/>/class-passes/</div>"]
        clientClassPass(["<div style='width:240px'><b>Client class pass</b><br/>/client-class-passes/</div>"])
        booking("<div style='width:240px'><b>Booking</b><br/>/bookings/</div>")
        clientClassPass -->|"<div style='width:170px'>class_pass_id</div>"| classPass
        booking -->|"<div style='width:170px'>client_class_pass_id</div>"| clientClassPass
    end
    subgraph privateSessions ["Private appointments"]
        direction LR
        appointmentPass["<div style='width:240px'><b>Appointment pass</b><br/>/appointment-passes/</div>"]
        clientAppointmentPass(["<div style='width:240px'><b>Client appointment pass</b><br/>/client-appointment-passes/</div>"])
        appointment("<div style='width:240px'><b>Appointment</b><br/>/appointments/</div>")
        clientAppointmentPass -->|"<div style='width:170px'>appointment_pass_id</div>"| appointmentPass
        appointment -.->|"<div style='width:170px'>spends credits of</div>"| clientAppointmentPass
    end
    class classPass,appointmentPass definition
    class clientClassPass,clientAppointmentPass held
    class booking,appointment record
    classDef definition fill:#beede5,stroke:#21837d,stroke-width:2px,color:#0f3d39
    classDef held fill:#ece4f8,stroke:#6b4fa3,stroke-width:2px,color:#35205f
    classDef record fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#5e2a0c
    classDef person fill:#e5eaea,stroke:#565e5d,stroke-width:2px,color:#1e2323
    linkStyle default stroke-width:1.5px

A booking names the client class pass to use. An appointment does not: bsport spends the credits of the compatible client appointment pass that expires first. The credits come from the slot's credit_price.