availabilityToken.
Send Authorization: Bearer <access_token> with every request. Write requests
also require an Idempotency-Key. See the idempotency contract
for retry rules.
Lesson capacity
Capacity uses the first positive limit in this order: the occurrence override, the recurring-series override, then the event template’sgroupSize.
Occurrences without an override inherit later series changes. An explicit
occurrence limit takes precedence, even when smaller than the series limit.
Availability, booking requests, confirmations, and waitlist operations use this
capacity. Permissions, waiting-list settings, and coach overbooking rules apply.
Scopes
| Scope | Allows |
|---|---|
calendar_events:read | List and read calendar events. |
event_types:read | List and read event type labels used by event templates. |
event_types:write | Create, update, and archive event type labels. |
event_templates:read | List and read event templates used by calendar availability and bookings. |
event_templates:write | Create, update, and archive event templates. |
recurring_bookings:read | List and read recurring booking chains. |
recurring_bookings:write | Update recurring booking settings and cancel a recurring chain. |
calendar_tasks:read | List and read blocking calendar tasks. |
calendar_tasks:write | Create, update, and cancel blocking calendar tasks. |
booking_requests:read | List booking requests. |
booking_requests:write | Approve or reject pending booking requests. |
coach_availability:read | Read coach availability templates. |
coach_availability:write | Replace coach availability templates. |
location_availability:read | Read location availability templates. |
location_availability:write | Replace location availability templates. |
availability_rules:read | Read availability closure metadata. |
availability_rules:write | Replace company availability closure metadata. |
availability:read | List bookable availability slots and receive short-lived availability tokens. |
bookings:read | List bookings, read booking details, and read cancellation context. |
bookings:write | Create bookings, update attendance, and cancel bookings. |
Event types
Event types label and categorize event templates for filtering and display.GET /public/v1/event-types
POST /public/v1/event-types
GET /public/v1/event-types/{eventTypeId}
PATCH /public/v1/event-types/{eventTypeId}
POST /public/v1/event-types/{eventTypeId}/archive
event_types:read for reads, event_types:write for writes.
Event type fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
eventTypeId | string | no | Event type ID. |
name | object | no | Names by language code. |
defaultLanguage | string | yes | Declared source language; null if unknown. |
normalizedName | string | no | Lowercase display name used for matching. |
archived | boolean | no | Whether the event type is archived. |
createdAt | string | yes | Creation timestamp. |
updatedAt | string | yes | Update timestamp. |
| Input | Rule |
|---|---|
eventTypeId | Must be a valid 24-character hexadecimal ObjectId. |
name | Required on create. Complete language map; must contain defaultLanguage. Omit on PATCH to preserve. |
defaultLanguage | Required on create; one of nl, en, de, fr, es. PATCH may omit it when the stored source is known. |
nl, en, de, fr, and es. Unsupported language
codes and the sourceLanguage input return 400.
A language map replaces all translations for that field. Changing
defaultLanguage requires that language in every retained nonempty text map.
{ "defaultLanguage": "nl", "name": { "nl": "Groepsles", "en": "Group class" } }
Event templates
Event templates define the name, duration, default location, capacity, booking rules, visibility, pricing, credits, and optionaleventType label for events.
GET /public/v1/event-templates?page=1&limit=100&eventType=Group
POST /public/v1/event-templates
GET /public/v1/event-templates/{eventTemplateId}
PATCH /public/v1/event-templates/{eventTemplateId}
POST /public/v1/event-templates/{eventTemplateId}/archive
event_templates:read for reads, event_templates:write for
writes.
List response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.page | integer | no | Current page. |
data.limit | integer | no | Page size after applying the maximum. |
data.total | integer | no | Total matching event templates. |
data.totalPages | integer | no | Number of pages. |
data.hasNextPage | boolean | no | Whether another page exists. |
data.hasPrevPage | boolean | no | Whether a previous page exists. |
data.eventTemplates[] | array | no | Event templates. |
| Field | Type | Nullable | Description |
|---|---|---|---|
eventTemplateId | string | no | Event template ID. |
name | object | no | Names by language code. |
defaultLanguage | string | yes | Declared source language; null if unknown. |
description | object | no | Descriptions by language code, or {}. |
duration | string | no | Duration value, expressed as a string. |
durationType | string | no | Duration unit; defaults to Minutes. |
defaultLocationId | string | yes | Default location ID, or null for a locationless template. |
color | string | no | Display color. |
groupSize | number | yes | Maximum group size when configured. |
enforceGroupSizeLimit | boolean | no | Whether group size is enforced. |
isOnline | boolean | no | Whether the template is online. |
blockCalendarCheck | boolean | no | Whether events based on this template block coach availability. |
blockLocationCheck | boolean | no | Whether events based on this template block location availability. |
bookingOption | string | no | Booking option key. |
cancellationPolicy | string | no | Cancellation policy key. |
waitingList | string | no | Waiting-list mode key. |
eventType | string | no | Calendar label/category for filtering and display. |
clientCalendarVisibilityMode | string | no | Client calendar visibility mode. |
pricing.price | number | yes | Price including VAT, when configured. |
pricing.currency | string | no | ISO currency code. |
pricing.vatPercentage | number | yes | VAT percentage. |
creditRequirement.credits | number | no | Credits required per booking. |
mediaCount | integer | no | Number of linked media items. |
archived | boolean | no | Whether the template is archived. |
createdAt | string | yes | Creation timestamp. |
updatedAt | string | yes | Update timestamp. |
| Input | Rule |
|---|---|
page | Integer, minimum 1. |
limit | Integer, default 10, maximum 100. |
eventType | Optional exact label filter. |
eventTemplateId | Must be a valid 24-character hexadecimal ObjectId. |
name | Required on create. Complete language map; must contain defaultLanguage. |
description | Complete language map containing defaultLanguage, or {} to clear. |
defaultLanguage | Required on create; one of nl, en, de, fr, es. PATCH may omit it when the stored source is known. |
duration | Required on create. |
defaultLocationId | Optional; must reference an active company location when supplied. Send null to clear. |
groupSize, creditPerBooking, pricing.price, pricing.vatPercentage | Must be numeric when supplied. |
pricing.currency | Uppercased; defaults to EUR when omitted inside pricing. |
List calendar events
GET /public/v1/calendar-events?dateFrom=2026-07-01T00:00:00.000Z&dateTo=2026-07-31T23:59:59.999Z
Authorization: Bearer <access_token>
calendar_events:read
Validation:
| Parameter | Type | Required | Rule |
|---|---|---|---|
dateFrom | ISO date-time | yes | Valid date-time. |
dateTo | ISO date-time | yes | Valid date-time, must be after dateFrom. |
coachId | string | no | Must be a valid coach ObjectId in the company. |
| Field | Type | Nullable | Description |
|---|---|---|---|
data.dateFrom | string | no | UTC ISO range start after parsing. |
data.dateTo | string | no | UTC ISO range end after parsing. |
data.truncated | boolean | no | true when recurrence or result safety limits were hit. |
data.events[] | array | no | Calendar occurrence summaries. |
data.events[].eventId | string | no | Calendar event ID. |
data.events[].name | object | no | Event names by language code. |
data.events[].defaultLanguage | string | yes | Declared source language, or null. |
data.events[].startAt | string | yes | Occurrence start. |
data.events[].endAt | string | yes | Occurrence end. |
data.events[].isRecurring | boolean | no | Whether the occurrence comes from recurrence. |
Get calendar event
GET /public/v1/calendar-events/{eventId}
Authorization: Bearer <access_token>
calendar_events:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.event.eventId | string | no | Calendar event ID. |
data.event.masterId | string | yes | Master recurring event ID for exception instances. |
data.event.name | object | no | Event names by language code. |
data.event.defaultLanguage | string | yes | Declared source language, or null. |
data.event.startAt | string | yes | Event start. |
data.event.endAt | string | yes | Event end. |
data.event.isRecurring | boolean | no | Whether this is recurring or linked to recurrence. |
data.event.timeZone | string | no | Event timezone when configured. |
data.event.templateId | string | yes | Event template ID. |
data.event.locationId | string | yes | Location ID. |
data.event.coaches[] | array | no | Assigned coaches. |
data.event.coaches[].coachId | string | no | Coach ID. |
data.event.coaches[].name | string | no | Coach display name. |
Recurring bookings
Read recurring booking chains, update payment or end settings, manage pause windows, and cancel a chain.List recurring bookings
GET /public/v1/recurring-bookings?page=1&limit=100
Authorization: Bearer <access_token>
recurring_bookings:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.page | integer | no | Current page. |
data.limit | integer | no | Page size after cap, maximum 100. |
data.total | integer | no | Total recurring booking chains. |
data.totalPages | integer | no | Total pages. |
data.hasNextPage | boolean | no | Next page availability. |
data.hasPrevPage | boolean | no | Previous page availability. |
data.recurringBookings[].recurringBookingId | string | no | Recurring booking chain ID. |
data.recurringBookings[].client.name | string | no | Client display name. |
data.recurringBookings[].status | string | no | Chain status. |
data.recurringBookings[].repeatInterval | string | no | Repeat interval. |
data.recurringBookings[].startDate | string | yes | Chain start. |
data.recurringBookings[].endDate | string | yes | Chain end. |
data.recurringBookings[].numberOfSessions | number | yes | Session count when configured. |
data.recurringBookings[].isContinuous | boolean | no | Whether chain is continuous. |
Get recurring booking
GET /public/v1/recurring-bookings/{recurringBookingId}
Authorization: Bearer <access_token>
recurring_bookings:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.recurringBooking.recurringBookingId | string | no | Recurring booking chain ID. |
data.recurringBooking.status | string | no | Chain status. |
data.recurringBooking.repeatInterval | string | no | Repeat interval. |
data.recurringBooking.startDate | string | yes | Chain start. |
data.recurringBooking.endDate | string | yes | Chain end. |
data.recurringBooking.numberOfSessions | number | yes | Session count when configured. |
data.recurringBooking.isContinuous | boolean | no | Whether chain is continuous. |
data.recurringBooking.paymentMethod | string | no | Chain payment method. |
data.recurringBooking.eventId | string | yes | Linked calendar event ID. |
data.recurringBooking.client.clientId | string | no | Client ID. |
data.recurringBooking.client.name | string | no | Client display name. |
data.recurringBooking.pauseWindows[].startDate | string | yes | Active pause window start. |
data.recurringBooking.pauseWindows[].endDate | string | yes | Active pause window end. |
data.recurringBooking.pauseWindows[].reason | string | no | Public pause reason. |
Update recurring booking
PATCH /public/v1/recurring-bookings/{recurringBookingId}
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
recurring_bookings:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
paymentMethod | string | no | Free, CreditsOnly, or CreditsOrInvoice. |
endDate | ISO date-time | conditional | One end mode only. Must be after the chain start date. |
numberOfSessions | integer | conditional | One end mode only. Minimum 1, maximum 520. |
isContinuous | boolean | conditional | One end mode only. Clears endDate and numberOfSessions when true. |
pauseWindow.startDate | ISO date-time | no | Required when pauseWindow is supplied. |
pauseWindow.endDate | ISO date-time | no | Required when pauseWindow is supplied and must be after start. |
pauseWindow.reason | string | no | Pause reason, maximum 500 characters. |
clearPauseWindows | boolean | no | When true, active pause windows are marked cleared. |
PUBLIC_API_UNKNOWN_FIELDS.
Returns data.recurringBooking with the same fields as the detail response,
plus:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.updatedFields[] | string[] | no | Field groups changed by this request. |
Cancel recurring booking
POST /public/v1/recurring-bookings/{recurringBookingId}/cancel
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
recurring_bookings:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
reason | string | no | Cancellation reason, maximum 500 characters. |
Cancelled and preserves its history and existing
booking records.
Returns data.recurringBooking with the same fields as the detail response,
plus:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.cancelled | boolean | no | true when the chain was cancelled. |
Calendar tasks
GET /public/v1/calendar-tasks?dateFrom=2026-07-01T00:00:00.000Z&dateTo=2026-07-31T23:59:59.999Z
Authorization: Bearer <access_token>
calendar_tasks:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.dateFrom | string | no | UTC ISO range start after parsing. |
data.dateTo | string | no | UTC ISO range end after parsing. |
data.truncated | boolean | no | true when recurrence/result safety limits were hit. |
data.tasks[].taskId | string | no | Task ID. |
data.tasks[].title | string | no | Task title. |
data.tasks[].notes | string | no | Task notes. |
data.tasks[].blockingScope | string | no | Blocking scope. |
data.tasks[].startAt | string | yes | Start timestamp. |
data.tasks[].endAt | string | yes | End timestamp. |
data.tasks[].isRecurring | boolean | no | Whether recurring. |
data.tasks[].timeZone | string | no | Timezone. |
data.tasks[].color | string | no | Display color. |
data.tasks[].coaches[] | array | no | Assigned coach summaries. |
data.tasks[].coaches[].coachId | string | no | Coach ID. |
data.tasks[].coaches[].name | string | no | Coach display name. |
Get calendar task
GET /public/v1/calendar-tasks/{taskId}
Authorization: Bearer <access_token>
calendar_tasks:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.task.taskId | string | no | Task ID. |
data.task.title | string | no | Task title. |
data.task.notes | string | no | Task notes. |
data.task.blockingScope | string | no | Blocking scope. |
data.task.startAt | string | yes | Start timestamp. |
data.task.endAt | string | yes | End timestamp. |
data.task.isRecurring | boolean | no | Whether recurring. |
data.task.timeZone | string | no | Timezone. |
data.task.color | string | no | Display color. |
data.task.coaches[].coachId | string | no | Coach ID. |
data.task.coaches[].name | string | no | Coach display name. |
Create calendar task
POST /public/v1/calendar-tasks
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
calendar_tasks:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
title | string | yes | Task title. |
startAt | ISO date-time | yes | Start timestamp. |
endAt | ISO date-time | conditional | End timestamp when not using duration. |
durationMinutes | integer | conditional | Duration when not using explicit endAt. |
notes | string | no | Task notes. |
assignedCoachIds[] | string[] | no | Coaches must belong to the authenticated company. |
PUBLIC_API_UNKNOWN_FIELDS.
Returns data.task with the same fields as the detail response.
Update calendar task
PATCH /public/v1/calendar-tasks/{taskId}
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
calendar_tasks:write
Allowed fields: title, startAt, endAt, durationMinutes, notes, and
assignedCoachIds. Unknown fields are rejected. Empty updates return
NOTHING_TO_UPDATE.
Returns data.task with the same fields as the detail response.
Cancel calendar task
POST /public/v1/calendar-tasks/{taskId}/cancel
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
calendar_tasks:write
Cancels the calendar task and returns its previous and new state.
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.taskId | string | no | Cancelled task ID. |
data.previousState.recurrenceStatus | string | no | Previous recurrence status, usually confirmed. |
data.newState.recurrenceStatus | string | no | cancelled. |
data.newState.deleted | boolean | no | Whether cancellation removed the task record. |
Booking requests
GET /public/v1/booking-requests?status=pending
Authorization: Bearer <access_token>
booking_requests:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.bookingRequests[].bookingRequestId | string | no | Booking request ID. |
data.bookingRequests[].client.clientId | string | no | Client ID. |
data.bookingRequests[].client.name | string | no | Client display name. |
data.bookingRequests[].calendarEventId | string | yes | Calendar event ID. |
data.bookingRequests[].lessonId | string | yes | Lesson/template ID. |
data.bookingRequests[].bookingId | string | yes | Linked booking ID. |
data.bookingRequests[].instanceDate | string | yes | Recurring instance date. |
data.bookingRequests[].status | string | no | Request status. |
data.bookingRequests[].capacity.booked | number | yes | Booked count. |
data.bookingRequests[].capacity.waiting | number | yes | Waiting count. |
data.bookingRequests[].capacity.total | number | yes | Total capacity. |
data.bookingRequests[].capacity.available | number | yes | Available seats. |
data.bookingRequests[].capacity.hasWaitingList | boolean | no | Waiting-list flag. |
data.bookingRequests[].lesson.name | string | no | Lesson name. |
data.bookingRequests[].lesson.type | string | no | Lesson type. |
data.bookingRequests[].createdAt | string | yes | Creation timestamp. |
data.bookingRequests[].updatedAt | string | yes | Last update timestamp. |
Approve booking request
POST /public/v1/booking-requests/{bookingRequestId}/approve
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
booking_requests:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
notifyClient | boolean | no | Whether the client should be notified. |
clientMessage | string | no | Optional message to the client. |
capacityAction | string | no | Empty string, reserve, waitlist_if_full, or force_overbook. |
| Field | Type | Nullable | Description |
|---|---|---|---|
data.bookingRequest.bookingRequestId | string | no | Booking request ID. |
data.bookingRequest.client.clientId | string | no | Client ID. |
data.bookingRequest.client.name | string | no | Client display name. |
data.bookingRequest.calendarEventId | string | yes | Calendar event ID. |
data.bookingRequest.lessonId | string | yes | Lesson/template ID. |
data.bookingRequest.bookingId | string | yes | Linked booking ID. |
data.bookingRequest.instanceDate | string | yes | Recurring instance date. |
data.bookingRequest.status | string | no | Updated request status. |
data.bookingRequest.capacity.booked | number | yes | Booked count. |
data.bookingRequest.capacity.waiting | number | yes | Waiting count. |
data.bookingRequest.capacity.total | number | yes | Total capacity. |
data.bookingRequest.capacity.available | number | yes | Available seats. |
data.bookingRequest.capacity.hasWaitingList | boolean | no | Waiting-list flag. |
data.bookingRequest.capacity.waitingListCapacity | number | yes | Waiting-list capacity. |
data.bookingRequest.lesson.name | string | no | Lesson name. |
data.bookingRequest.lesson.type | string | no | Lesson type. |
data.bookingRequest.lesson.enforceGroupSizeLimit | boolean | no | Group-size enforcement flag. |
data.bookingRequest.createdAt | string | yes | Creation timestamp. |
data.bookingRequest.updatedAt | string | yes | Last update timestamp. |
data.action.status | string | no | accepted. |
data.action.appliedAt | string | no | Decision timestamp. |
Reject booking request
POST /public/v1/booking-requests/{bookingRequestId}/reject
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
booking_requests:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
notifyClient | boolean | no | Whether the client should be notified. |
clientMessage | string | no | Optional message to the client. |
rejectionReason | string | no | Rejection reason. |
canClientRequestAgain | boolean | no | Whether the client may submit another request. |
requestAgainAfterMinutes | integer | no | Delay before another request is allowed. |
data.bookingRequest with the same fields as the approval response,
plus:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.action.status | string | no | rejected. |
data.action.appliedAt | string | no | Decision timestamp. |
Coach availability
Manage a coach’s working hours, date-specific availability, and days off. Use bookable availability to find slots that clients can book.GET /public/v1/coaches/{coachId}/availability
Authorization: Bearer <access_token>
coach_availability:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.coachAvailability | object | yes | Coach availability template, or null when none has been configured. |
data.coachAvailability.coachId | string | no | Coach ID from the path. |
data.coachAvailability.availabilityPeriods[] | array | no | Date-ranged weekly availability templates. |
data.coachAvailability.availabilityPeriods[].startDate | string | yes | Period start in UTC. |
data.coachAvailability.availabilityPeriods[].endDate | string | yes | Period end in UTC, or null for open-ended periods. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[] | array | no | Weekly day rules for this period. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[].dayOfWeek | integer | yes | Day index, 0 for Sunday through 6 for Saturday. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[].isDayOff | boolean | no | Whether this weekday is blocked. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[].slots[] | array | no | Coach working-time slots for the day. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[].slots[].locationId | string | no | Location ID for this slot, when set. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[].slots[].zoneKey | string | yes | Location zone key, when set. |
data.coachAvailability.availabilityPeriods[].weeklyPattern[].slots[].allowedEventTemplateIds[] | string[] | no | Event templates that can derive bookable slots from this coach slot. |
data.coachAvailability.specificAvailability[] | array | no | Ad-hoc date-specific working slots. |
data.coachAvailability.overrides[] | array | no | Date-specific blocks such as day off, sick, or holiday. |
data.coachAvailability.settings | object | no | Booking-window, buffer, placement, and template fallback settings. |
data.coachAvailability.createdAt | string | yes | Creation timestamp. |
data.coachAvailability.updatedAt | string | yes | Last update timestamp. |
Replace coach availability
PUT /public/v1/coaches/{coachId}/availability
Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: <stable_request_key>
coach_availability:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
availabilityPeriods[] | array | no | Full replacement date-ranged weekly templates. |
availabilityPeriods[].weeklyPattern[].slots[] | array | no | Slot objects with startTime, endTime, optional locationId, optional zoneKey, and optional allowedEventTemplateIds[]. |
specificAvailability[] | array | no | Full replacement ad-hoc date availability. |
overrides[] | array | no | Full replacement date blocks. Supported types are DayOff, Sick, and Holiday. |
settings | object | no | Full replacement booking-window and placement settings. |
Location availability
Manage a location’s weekly availability and date overrides. These rules are separate from its public opening hours. Use bookable availability to find slots that clients can book.GET /public/v1/locations/{locationId}/availability
Authorization: Bearer <access_token>
location_availability:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.locationAvailability | object | yes | Location availability template, or null when none has been configured. |
data.locationAvailability.locationId | string | no | Location ID from the path. |
data.locationAvailability.weeklyPattern[] | array | no | Weekly location availability rules. |
data.locationAvailability.weeklyPattern[].dayOfWeek | integer | yes | Day index, 0 for Sunday through 6 for Saturday. |
data.locationAvailability.weeklyPattern[].isDayOff | boolean | no | Whether this weekday is blocked. |
data.locationAvailability.weeklyPattern[].allowedEventTemplateIds[] | string[] | no | Day-level event template restrictions. |
data.locationAvailability.weeklyPattern[].slots[] | array | no | Location availability slots for the day. |
data.locationAvailability.weeklyPattern[].slots[].startTime | string | no | Slot start time, HH:mm. |
data.locationAvailability.weeklyPattern[].slots[].endTime | string | no | Slot end time, HH:mm. |
data.locationAvailability.weeklyPattern[].slots[].allowedEventTemplateIds[] | string[] | no | Slot-level event template restrictions. |
data.locationAvailability.overrides[] | array | no | Date-specific day off, maintenance, or custom-hour overrides. |
data.locationAvailability.settings | object | no | Booking-window, buffer, calendar-blocking, and template fallback settings. |
data.locationAvailability.createdAt | string | yes | Creation timestamp. |
data.locationAvailability.updatedAt | string | yes | Last update timestamp. |
Replace location availability
PUT /public/v1/locations/{locationId}/availability
Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: <stable_request_key>
location_availability:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
weeklyPattern[] | array | no | Full replacement weekly location availability template. |
weeklyPattern[].slots[] | array | no | Slot objects with startTime, endTime, and optional allowedEventTemplateIds[]. |
overrides[] | array | no | Full replacement date overrides. Supported types are DayOff, CustomHours, and Maintenance. |
settings | object | no | Full replacement booking-window, buffer, calendar-blocking, and template fallback settings. |
Closure days and absence
Manage holiday presets and custom closure or absence dates that block availability for coaches, locations, or both.GET /public/v1/availability-closures
Authorization: Bearer <access_token>
availability_rules:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.availabilityClosures.presets[].key | string | no | Preset key. |
data.availabilityClosures.presets[].enabled | boolean | no | Whether this holiday preset blocks availability. |
data.availabilityClosures.presets[].appliesToCoaches | boolean | no | Whether the preset blocks coach availability. |
data.availabilityClosures.presets[].appliesToLocations | boolean | no | Whether the preset blocks location availability. |
data.availabilityClosures.presets[].holidayKeys[] | string[] | no | Holiday keys selected from this preset. |
data.availabilityClosures.presets[].coachIds[] | string[] | no | Scoped coach IDs. |
data.availabilityClosures.presets[].locationIds[] | string[] | no | Scoped location IDs. |
data.availabilityClosures.customClosures[].key | string | no | Closure key. |
data.availabilityClosures.customClosures[].name | string | no | Closure name. |
data.availabilityClosures.customClosures[].date | string | no | Closure date. |
data.availabilityClosures.customClosures[].recurring | boolean | no | Recurring yearly flag. |
data.availabilityClosures.customClosures[].enabled | boolean | no | Whether this custom closure blocks availability. |
data.availabilityClosures.customClosures[].reason | string | no | Closure or absence note. |
data.availabilityClosures.customClosures[].appliesToCoaches | boolean | no | Whether the closure blocks coach availability. |
data.availabilityClosures.customClosures[].appliesToLocations | boolean | no | Whether the closure blocks location availability. |
data.availabilityClosures.customClosures[].locationIds[] | string[] | no | Scoped location IDs. |
data.availabilityClosures.customClosures[].coachIds[] | string[] | no | Scoped coach IDs. |
data.availabilityClosures.availablePresets[].key | string | no | Available preset key. |
data.availabilityClosures.availablePresets[].countryCode | string | yes | Preset country code. |
data.availabilityClosures.availablePresets[].regionCode | string | yes | Preset region code. |
data.availabilityClosures.availablePresets[].label.en | string | no | English preset label. |
data.availabilityClosures.availablePresets[].label.nl | string | no | Dutch preset label. |
data.availabilityClosures.availablePresets[].holidays[].key | string | no | Public holiday key. |
data.availabilityClosures.availablePresets[].holidays[].label.en | string | no | English holiday label. |
data.availabilityClosures.availablePresets[].holidays[].label.nl | string | no | Dutch holiday label. |
data.availabilityClosures.availablePresets[].holidays[].defaultEnabled | boolean | no | Whether the holiday is enabled by default. |
data.availabilityClosures.updatedAt | string | yes | Last update timestamp. |
Replace closure days and absence
PUT /public/v1/availability-closures
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
availability_rules:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
presets[] | array | no | Complete desired holiday preset array. |
customClosures[] | array | no | Complete desired custom closure and absence date array. |
presets and customClosures arrays. This endpoint replaces the configuration.
Unknown top-level fields are rejected.
The response returns data.availabilityClosures with the
same fields as the read response.
List bookable availability
GET /public/v1/availability?dateFrom=2026-07-20T00:00:00.000Z&dateTo=2026-07-27T23:59:59.999Z&eventTemplateId={templateId}
Authorization: Bearer <access_token>
availability:read
Returns slots that are currently bookable or available for the waiting list,
based on calendar events, coach and location availability, closures, capacity,
booking rules, and optional client context.
Each slot includes a signed, company-scoped availabilityToken that expires
after 10 minutes. It does not reserve the slot. Creating a booking revalidates
capacity and booking eligibility.
Validation:
| Parameter | Type | Required | Rule |
|---|---|---|---|
dateFrom | ISO date-time | yes | Valid date-time. |
dateTo | ISO date-time | yes | Valid date-time, must be after dateFrom. |
page | integer | no | Minimum 1. |
limit | integer | no | Default 10, maximum 100. |
clientId | string | no | When supplied, client must belong to the authenticated company. Client product visibility and duplicate-booking state are considered. |
eventTemplateId | string | no | Restrict to one event template. |
eventTemplateIds | comma-separated string | no | Restrict to multiple event templates. |
coachId | string | no | Restrict to slots assigned to this coach. |
locationId | string | no | Restrict to this location ID. |
| Field | Type | Nullable | Description |
|---|---|---|---|
data.dateFrom | string | no | Parsed UTC range start. |
data.dateTo | string | no | Parsed UTC range end. |
data.page | integer | no | Current page. |
data.limit | integer | no | Page size after cap. |
data.total | integer | no | Total matching slots. |
data.totalPages | integer | no | Total pages. |
data.hasNextPage | boolean | no | Next page availability. |
data.hasPrevPage | boolean | no | Previous page availability. |
data.slots[].slotId | string | no | Opaque slot ID. Use its availabilityToken to book the slot. |
data.slots[].availabilityToken | string | no | Short-lived signed token for booking this exact slot. |
data.slots[].calendarEventId | string | yes | Calendar event ID, or null when the event is created during booking. |
data.slots[].recurringMasterEventId | string | yes | Recurring master event ID when applicable. |
data.slots[].instanceDate | string | yes | Recurring occurrence date. |
data.slots[].eventTemplateId | string | yes | Template ID. |
data.slots[].name | string | no | Slot/event name. |
data.slots[].startAt | string | yes | Slot start in UTC. |
data.slots[].endAt | string | yes | Slot end in UTC. |
data.slots[].timeZone | string | no | Display time zone. |
data.slots[].coaches[] | array | no | Public coach references. |
data.slots[].coaches[].coachId | string | yes | Coach ID when visible. |
data.slots[].coaches[].name | string | no | Coach display name when visible. |
data.slots[].location.name | string | no | Location name. |
data.slots[].location.zone | string | no | Location zone. |
data.slots[].location.address | string | no | Location address when available. |
data.slots[].location.longitude | number | yes | Longitude. |
data.slots[].location.latitude | number | yes | Latitude. |
data.slots[].capacity.total | number | yes | Total bookable seats, or null when unlimited/not exposed. |
data.slots[].capacity.booked | number | yes | Booked seats. |
data.slots[].capacity.remaining | number | yes | Remaining seats. |
data.slots[].waitlist.available | boolean | no | Whether waitlist booking is available. |
data.slots[].waitlist.booked | number | yes | Current waitlist count. |
data.slots[].bookingMode | string | no | bookable, waitlist_available, full, or unavailable. |
data.slots[].pricing.price | number | yes | Price including VAT, when configured. |
data.slots[].pricing.currency | string | no | Currency code. |
data.slots[].pricing.vatPercentage | number | yes | VAT percentage. |
data.slots[].creditRequirement.credits | number | no | Credits required for booking. |
List bookings
GET /public/v1/bookings?dateFrom=2026-07-01T00:00:00.000Z&dateTo=2026-07-31T23:59:59.999Z&limit=50
Authorization: Bearer <access_token>
bookings:read
Validation:
| Parameter | Type | Required | Rule |
|---|---|---|---|
dateFrom | ISO date-time | yes | Valid date-time. |
dateTo | ISO date-time | yes | Valid date-time, max 92-day range. |
page | integer | no | Minimum 1. |
limit | integer | no | Default 50, maximum 50. |
status | string | no | Planned, Waiting, RequestPending, CancelledByClient, CancelledByCoach, Completed, or BookingRequestNotAccepted. |
clientId | string | no | Valid client ObjectId connected to the company. |
coachId | string | no | Valid coach ObjectId. |
| Field | Type | Nullable | Description |
|---|---|---|---|
data.page | integer | no | Current page. |
data.limit | integer | no | Page size. |
data.total | integer | no | Total matching bookings. |
data.totalPages | integer | no | Total pages. |
data.hasNextPage | boolean | no | Next page availability. |
data.hasPrevPage | boolean | no | Previous page availability. |
data.bookings[].bookingId | string | no | Booking ID. |
data.bookings[].status | string | no | Booking status. |
data.bookings[].attendanceStatus | string | no | Attendance status. |
data.bookings[].client | object | yes | Client summary, omitted when unavailable. |
data.bookings[].client.name | string | no | Client display name. |
data.bookings[].event.name | string | no | Event name. |
data.bookings[].event.startAt | string | yes | Booking event start. |
data.bookings[].event.endAt | string | yes | Booking event end. |
curl -H "Authorization: Bearer $FITSOCIETY_ACCESS_TOKEN" \
"https://api.fitsociety.io/public/v1/bookings?dateFrom=2026-07-01T00:00:00.000Z&dateTo=2026-07-31T23:59:59.999Z&status=Planned&limit=50"
const query = new URLSearchParams({
dateFrom: "2026-07-01T00:00:00.000Z",
dateTo: "2026-07-31T23:59:59.999Z",
status: "Planned",
limit: "50",
});
const response = await fetch(
`https://api.fitsociety.io/public/v1/bookings?${query}`,
{
headers: {
Authorization: `Bearer ${process.env.FITSOCIETY_ACCESS_TOKEN}`,
},
},
);
const body = await response.json();
console.log(body.data.total, body.data.bookings);
import os
import requests
response = requests.get(
"https://api.fitsociety.io/public/v1/bookings",
headers={"Authorization": f"Bearer {os.environ['FITSOCIETY_ACCESS_TOKEN']}"},
params={
"dateFrom": "2026-07-01T00:00:00.000Z",
"dateTo": "2026-07-31T23:59:59.999Z",
"status": "Planned",
"limit": 50,
},
)
response.raise_for_status()
body = response.json()
print(body["data"]["total"], body["data"]["bookings"])
{
"data": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false,
"bookings": [
{
"bookingId": "64b64c0f2f5f4c0012345680",
"status": "Planned",
"attendanceStatus": "unknown",
"client": { "name": "Jane Doe" },
"event": {
"name": "Small group training",
"startAt": "2026-07-21T08:00:00.000Z",
"endAt": "2026-07-21T09:00:00.000Z"
}
}
]
},
"meta": {
"requestId": "req_0123456789abcdef",
"rateLimit": { "limit": 10, "remaining": 9, "resetSeconds": 1 }
}
}
Get booking
GET /public/v1/bookings/{bookingId}
Authorization: Bearer <access_token>
bookings:read
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.booking.bookingId | string | no | Booking ID. |
data.booking.status | string | no | Booking status. |
data.booking.attendanceStatus | string | no | Attendance status. |
data.booking.paymentMethod | string | no | Booking payment method. |
data.booking.paymentProcessingStatus | string | no | Payment processing status. |
data.booking.usedCredits | number | no | Credits used by this booking. |
data.booking.createdByType | string | no | Creator type. |
data.booking.isRecurringInstance | boolean | no | Whether this belongs to a recurring booking. |
data.booking.recurringBookingId | string | yes | Recurring booking ID. |
data.booking.client.clientId | string | no | Client ID. |
data.booking.client.name | string | no | Client display name. |
data.booking.event.eventId | string | yes | Event ID. |
data.booking.event.name | string | no | Event name. |
data.booking.event.startAt | string | yes | Event start. |
data.booking.event.endAt | string | yes | Event end. |
data.booking.event.instanceDate | string | yes | Recurring instance date. |
Create booking
POST /public/v1/bookings
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
bookings:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
clientId | string | yes | Client must belong to the authenticated company. |
availabilityToken | string | conditional | Preferred. Token from GET /public/v1/availability. When supplied, caller-provided calendarEventId and instanceDate are ignored. |
calendarEventId | string | conditional | Required only when availabilityToken is not supplied. Event must belong to the authenticated company. |
instanceDate | string | no | ISO date-time for recurring occurrence bookings when booking directly by event ID. |
paymentMethod | string | no | product or free. Defaults to product. |
creditsToDeduct | number | no | Only used for product bookings. |
| Validation | Behavior |
|---|---|
| Token signature | Invalid signatures return 400 PUBLIC_API_AVAILABILITY_TOKEN_INVALID_SIGNATURE. |
| Token company | Company mismatch returns 403 PUBLIC_API_AVAILABILITY_TOKEN_COMPANY_MISMATCH. |
| Token expiry | Expired tokens return 400 PUBLIC_API_AVAILABILITY_TOKEN_EXPIRED. |
| Slot state | Slot is loaded again before booking; stale full/unavailable slots return a client error. |
| Slots without an event | A calendar event is created after availability is validated. |
| Duplicate bookings | Duplicate enrolments are rejected. |
| Capacity | Group-size and waiting-list rules apply. |
data.booking with the same fields as the detail response.
curl -X POST "https://api.fitsociety.io/public/v1/bookings" \
-H "Authorization: Bearer $FITSOCIETY_ACCESS_TOKEN" \
-H "Idempotency-Key: booking-create-jane-20260721-0800" \
-H "Content-Type: application/json" \
-d '{
"clientId": "64b64c0f2f5f4c0012345678",
"availabilityToken": "<availabilityToken from GET /public/v1/availability>",
"paymentMethod": "product"
}'
const headers = {
Authorization: `Bearer ${process.env.FITSOCIETY_ACCESS_TOKEN}`,
};
// 1. Fetch a bookable slot with its short-lived availabilityToken.
const availabilityQuery = new URLSearchParams({
dateFrom: "2026-07-20T00:00:00.000Z",
dateTo: "2026-07-27T23:59:59.999Z",
eventTemplateId: "64b64c0f2f5f4c0012345682",
});
const availability = await fetch(
`https://api.fitsociety.io/public/v1/availability?${availabilityQuery}`,
{ headers },
).then((res) => res.json());
const slot = availability.data.slots[0];
// 2. Book the slot. Availability tokens are not reservations, so book quickly.
const response = await fetch("https://api.fitsociety.io/public/v1/bookings", {
method: "POST",
headers: {
...headers,
"Idempotency-Key": "booking-create-jane-20260721-0800",
"Content-Type": "application/json",
},
body: JSON.stringify({
clientId: "64b64c0f2f5f4c0012345678",
availabilityToken: slot.availabilityToken,
paymentMethod: "product",
}),
});
const body = await response.json();
if (response.status === 201) {
console.log("Created booking", body.data.booking.bookingId);
}
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['FITSOCIETY_ACCESS_TOKEN']}"}
# 1. Fetch a bookable slot with its short-lived availabilityToken.
availability = requests.get(
"https://api.fitsociety.io/public/v1/availability",
headers=headers,
params={
"dateFrom": "2026-07-20T00:00:00.000Z",
"dateTo": "2026-07-27T23:59:59.999Z",
"eventTemplateId": "64b64c0f2f5f4c0012345682",
},
).json()
slot = availability["data"]["slots"][0]
# 2. Book the slot. Availability tokens are not reservations, so book quickly.
response = requests.post(
"https://api.fitsociety.io/public/v1/bookings",
headers={**headers, "Idempotency-Key": "booking-create-jane-20260721-0800"},
json={
"clientId": "64b64c0f2f5f4c0012345678",
"availabilityToken": slot["availabilityToken"],
"paymentMethod": "product",
},
)
response.raise_for_status()
body = response.json()
if response.status_code == 201:
print("Created booking", body["data"]["booking"]["bookingId"])
201 Created):
{
"data": {
"booking": {
"bookingId": "64b64c0f2f5f4c0012345680",
"status": "Planned",
"attendanceStatus": "unknown",
"paymentMethod": "product",
"paymentProcessingStatus": "none",
"usedCredits": 1,
"createdByType": "public_api",
"isRecurringInstance": false,
"recurringBookingId": null,
"client": {
"clientId": "64b64c0f2f5f4c0012345678",
"name": "Jane Doe"
},
"event": {
"eventId": "64b64c0f2f5f4c0012345681",
"name": "Small group training",
"startAt": "2026-07-21T08:00:00.000Z",
"endAt": "2026-07-21T09:00:00.000Z",
"instanceDate": null
}
}
},
"meta": {
"requestId": "req_0123456789abcdef",
"rateLimit": { "limit": 10, "remaining": 8, "resetSeconds": 1 }
}
}
Update booking attendance
PATCH /public/v1/bookings/{bookingId}
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
bookings:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
status | string | yes | attended, noshow, or unknown. |
instanceDate | string | no | ISO date-time for recurring instances. |
noShowReason | string | no | Max 500 characters. |
remarks | string | no | Max 1000 characters. |
| Field | Type | Nullable | Description |
|---|---|---|---|
data.attendance.calendarEventId | string | yes | Event ID. |
data.attendance.clientId | string | yes | Client ID. |
data.attendance.instanceDate | string | yes | Instance date. |
data.attendance.status | string | no | Applied status. |
data.attendance.attended | boolean | no | true only for attended. |
data.attendance.updatedAt | string | yes | Update timestamp. |
data.attendance.updatedBy.id | string | yes | Acting coach ID. |
data.attendance.updatedBy.name | string | no | Acting coach display name when available. |
Get booking cancellation context
GET /public/v1/bookings/{bookingId}/cancellation-context
Authorization: Bearer <access_token>
bookings:read
Optional query: clientId, instanceDate.
Response fields:
| Field | Type | Nullable | Description |
|---|---|---|---|
data.cancellationContext.bookingId | string | no | Booking ID. |
data.cancellationContext.clientId | string | no | Client ID. |
data.cancellationContext.calendarEventId | string | no | Event ID. |
data.cancellationContext.lessonId | string | no | Lesson/template ID. |
data.cancellationContext.occurrence.isRecurring | boolean | no | Whether cancellation targets a recurring occurrence. |
data.cancellationContext.occurrence.masterEventId | string | yes | Master event ID. |
data.cancellationContext.occurrence.exceptionEventId | string | yes | Exception event ID. |
data.cancellationContext.occurrence.instanceDate | string | yes | Instance date. |
data.cancellationContext.timing.startDate | string | yes | Event start. |
data.cancellationContext.timing.endDate | string | yes | Event end. |
data.cancellationContext.timing.isPast | boolean | no | Whether the event is in the past. |
data.cancellationContext.policy.defaultFinancialAction | string | no | Default action based on cancellation policy. |
data.cancellationContext.financial.availableActions[] | string[] | no | Allowed financial actions. |
data.cancellationContext.financial.chargeAllowed | boolean | no | Whether a charge action can be applied. |
data.cancellationContext.financial.hasCreditUsage | boolean | no | Whether credits were used. |
data.cancellationContext.financial.creditsUsed | number | no | Credits used. |
data.cancellationContext.financial.paymentMethod | string | no | Booking payment method. |
data.cancellationContext.financial.paymentProcessingStatus | string | no | Payment processing status. |
data.cancellationContext.financial.paymentTransactionId | string | no | Payment transaction reference when present. |
data.cancellationContext.reasons[].code | string | no | Configured cancellation reason code. |
data.cancellationContext.reasons[].label | string | no | Localized cancellation reason label. |
data.cancellationContext.reasons[].labels | object | no | Localized labels keyed by language. |
data.cancellationContext.reasons[].isDefault | boolean | no | Default reason flag. |
data.cancellationContext.reasons[].active | boolean | no | Active reason flag. |
data.cancellationContext.reasons[].requiresText | boolean | no | Whether extra text is required. |
data.cancellationContext.reasons[].sortOrder | number | no | Reason sort order. |
data.cancellationContext.requiresReason | boolean | no | Whether reason text/code is required. |
Cancel booking
POST /public/v1/bookings/{bookingId}/cancel
Authorization: Bearer <access_token>
Idempotency-Key: <stable_request_key>
Content-Type: application/json
bookings:write
Request body:
| Field | Type | Required | Rule |
|---|---|---|---|
clientId | string | no | Optional client ID to verify booking ownership. |
instanceDate | string | no | Required by some recurring occurrence cancellations. |
financialAction | string | no | followPolicy, refund, retain, or charge. Defaults to followPolicy. |
overridePolicy | boolean | no | Applies only when explicitly true. |
chargeClientCreditId | string | conditional | Required when financialAction resolves to charge. |
chargeCredits | number | conditional | Required when charging credits. |
cancellationReasonCode | string | no | Must match a configured reason when supplied. |
cancellationReasonText | string | no | Custom reason text. |
coachNote | string | no | Note included in booking history and notifications. |
notifyClient | boolean | no | Defaults to false in Public API. |
notifyCoach | boolean | no | Defaults to false. |
promoteWaitlist | boolean | no | Defaults to true. |
| Field | Type | Nullable | Description |
|---|---|---|---|
data.bookingId | string | no | Booking ID. |
data.bookingStatus | string | no | Final booking status. |
data.status | string | no | Final booking status. |
data.alreadyCancelled | boolean | no | Whether the booking was already cancelled. |
data.financial.actionApplied | string | no | refund, retain, or charge. |
data.financial.creditsRefunded | number | no | Refunded credits. |
data.financial.singleSessionReset | boolean | no | Whether a single-session credit was reset. |
data.financial.creditsCharged | number | no | Charged credits. |
data.financial.chargedClientCreditId | string | yes | Credit ID used for charge. |
data.financial.chargeCreditUsages[].clientCreditId | string | no | Client credit ID charged. |
data.financial.chargeCreditUsages[].creditsUsed | number | no | Credits charged from this credit record. |
data.financial.chargeCreditUsages[].usageType | string | no | Usage type. |
data.financial.chargeCreditUsages[].creditPoolKey | string | no | Credit pool key. |
data.financial.chargeCreditUsages[].creditPoolName | string | no | Credit pool name. |
data.financial.chargeCreditUsages[].creditPoolMode | string | no | Credit pool mode. |
data.policy.policy | string | no | Cancellation policy key used for evaluation. |
data.policy.customCancellationPolicyHours | number | no | Custom policy window in hours. |
data.policy.eventStartAt | string | yes | Event start used for policy evaluation. |
data.policy.evaluatedAt | string | no | Policy evaluation timestamp. |
data.policy.refundEligible | boolean | no | Whether policy allowed a refund. |
data.policy.overridePolicy | boolean | no | Whether the request overrode policy. |
curl -X POST "https://api.fitsociety.io/public/v1/bookings/64b64c0f2f5f4c0012345680/cancel" \
-H "Authorization: Bearer $FITSOCIETY_ACCESS_TOKEN" \
-H "Idempotency-Key: booking-cancel-64b64c0f2f5f4c0012345680" \
-H "Content-Type: application/json" \
-d '{
"financialAction": "followPolicy",
"cancellationReasonText": "Client is ill",
"notifyClient": true
}'
const bookingId = "64b64c0f2f5f4c0012345680";
const response = await fetch(
`https://api.fitsociety.io/public/v1/bookings/${bookingId}/cancel`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FITSOCIETY_ACCESS_TOKEN}`,
"Idempotency-Key": `booking-cancel-${bookingId}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
financialAction: "followPolicy",
cancellationReasonText: "Client is ill",
notifyClient: true,
}),
},
);
const body = await response.json();
console.log(body.data.bookingStatus, body.data.financial.actionApplied);
import os
import requests
booking_id = "64b64c0f2f5f4c0012345680"
response = requests.post(
f"https://api.fitsociety.io/public/v1/bookings/{booking_id}/cancel",
headers={
"Authorization": f"Bearer {os.environ['FITSOCIETY_ACCESS_TOKEN']}",
"Idempotency-Key": f"booking-cancel-{booking_id}",
},
json={
"financialAction": "followPolicy",
"cancellationReasonText": "Client is ill",
"notifyClient": True,
},
)
response.raise_for_status()
body = response.json()
print(body["data"]["bookingStatus"], body["data"]["financial"]["actionApplied"])
{
"data": {
"bookingId": "64b64c0f2f5f4c0012345680",
"bookingStatus": "CancelledByCoach",
"status": "CancelledByCoach",
"alreadyCancelled": false,
"financial": {
"actionApplied": "refund",
"creditsRefunded": 1,
"singleSessionReset": false,
"creditsCharged": 0,
"chargedClientCreditId": null,
"chargeCreditUsages": []
},
"policy": {
"policy": "flexible",
"customCancellationPolicyHours": 24,
"eventStartAt": "2026-07-21T08:00:00.000Z",
"evaluatedAt": "2026-07-20T09:15:00.000Z",
"refundEligible": true,
"overridePolicy": false
}
},
"meta": {
"requestId": "req_0123456789abcdef",
"rateLimit": { "limit": 10, "remaining": 7, "resetSeconds": 1 }
}
}
Calendar query work budgets
Calendar occurrence lists apply cancellations and replacements before counting and paging. Normal pages returntruncated=false. For very dense recurrence
rules, large candidate/exception sets, or rules whose old start date requires too
much scan work, the API returns 400 PUBLIC_API_CALENDAR_QUERY_TOO_COMPLEX.
Use a smaller date range or more specific filters, then continue pagination.
The error is explicit; the API never presents a partial occurrence set as complete.