Skip to content

Data model and terminology

This page explains the names the V2 REST API uses for resources and fields, and how they relate to the names in the Back Office. Use it to pick the right resource and field names when you build against V2.

Company and venue

A company is the business whose data you access through the Public API or MCP. A venue is a physical place associated with one or more companies. Use the company identifier for company scope and the venue identifier when selecting a physical place.

venue is the resource name in the Public API and the Back Office. Older surfaces call the same place an establishment. Do not confuse it with a Back Office location, which is a group of venues billed as one entity.

Client

client is the V2 resource name (/clients/). In the Back Office, "client" is the umbrella term for leads, customers and members.

consumer, customer, and user describe the platform-wide account in older surfaces. They are not client identifiers and must not be used to call /clients/{id}/.

Class, appointment, and service

Read the table by term. It shows what each term is and where it appears in V2.

Term What it is Where it appears
class A group fitness session with a fixed schedule and capacity. /classes/ endpoint
appointment A private 1-on-1 session booked by one client with one teacher. /appointments/ endpoint
service The offering above the class instance, for example "Yoga" or "Personal Training". A single service can have many class instances. /services/ endpoint, service_id on /classes/
appointment service The template behind private sessions. /appointment-services/ endpoint, appointment_service_id on /appointments/

Bookings use class_id and class_ids for the related class. V2 has no separate session resource.

Using a booking class identifier to fetch class details

Use class_id directly with GET /api/v2/management/classes/{class_id}/.

V2 booking filters accept only service IDs, through ?service_ids=.

Appointments, appointment services, and appointment slots

Three resources describe a private session. The diagram of how they point to each other is in How appointments, services and slots relate.

Read the table by resource.

Resource What it is Key fields
Appointment service The private-session offering a client books, for example a massage. name, description, appointment_slot_ids
Appointment slot One duration and credit-price option of a service. A service can have several slots, for example 30 minutes for 1 credit and 60 minutes for 2 credits. appointment_service_id, duration_in_minutes, credit_price, is_active
Appointment One private session booked by one client on one slot, starting at a chosen time. appointment_service_id, appointment_slot_id, client_id, teacher_id, venue_id, starts_at, credit_price

A slot describes a duration and a credit cost, not a time on the calendar. Listing appointments returns existing bookings, and V2 has no availability search: you choose the starts_at when you book. To book, pick a slot from the service's appointment_slot_ids, then follow Book an appointment.

Add expand[]=appointment_slot_id or expand[]=appointment_service_id to replace the ID with the full object. appointment_service_id replaces the V1 service_id on appointments.

Teacher

V2 exposes the company-scoped instructor record under the term teacher.

Term What it is Where it appears
teacher An instructor associated with a specific studio. /teachers/ endpoint, and teacher_id fields and filters on /classes/, /appointments/ and /bookings/
coach The platform-level instructor account shared across studios. Legacy Back Office surfaces and V1. V2 uses teacher IDs instead

V2 teacher IDs are always company-scoped IDs returned by the Teachers endpoint. Never reuse an ID from V1 without checking the migration guide.

Class passes, appointment passes, and subscriptions

A class pass grants access to group classes, while an appointment pass grants access to private appointments. "Passes" is the Back Office term for both types. The table shows the resource for each product and for the product owned by a client.

Product Product owned by a client
class_pass client_class_pass
appointment_pass client_appointment_pass
subscription client_subscription

A subscription is a subscription product, and a client_subscription is an active subscription owned by a client. The Back Office calls a subscription a membership.

For how a pass reaches a booking or an appointment, see Which pass pays for a booking.

Other objects added in V2

These objects have no V1 equivalent. Read the table by object. The endpoints are under /api/v2/management/.

Object Endpoint What it is
Level /levels/ The difficulty level a class can carry, sent as level_id when you create or update a class. It lists your company's levels and the levels shared across companies. Retired levels stay listed with is_active set to false.
Discount code /coupons/ A code that takes money off a one-off purchase. type is standard or unique_codes, and applies_to sets the scope: all purchases, class passes, products, delivery fees, appointment passes or bundles. The API calls it a coupon.
Discount code usage /coupon-usages/ One record each time a discount code is applied to a purchase. It links the code (coupon_id), the client (client_id) and the invoice (invoice_id), and is_reverted shows whether the discount was reversed. Read only.
Gift card /gift-cards/ A prepaid value a client can buy and spend. type is fixed_amount or flexible_amount, and flexible cards have a minimum and a maximum amount.
Product /products/ A retail product sold by the studio. type is standalone, base or variant. A base product groups variants, and each variant points to its base through base_product_id and differs by color or size.
Invoice /invoices/ The commercial document for a purchase. It has a status (draft, open, paid, voided or refunded), its amounts and its line_items.
Invoice item /invoice-items/ One line of an invoice, linked by invoice_id. It shows the original, discount and total amounts, and whether the line is refunded.
Teacher pay rate /teacher-pay-rates/ A rule for how a teacher is paid. applies_to is class, appointment, group_class or workshop, with base, minimum and maximum amounts and bonuses. You assign it from /teachers/{id}/pay-rates/.
Communication /communications/ An email or SMS queued through the API, with a processing status of queued, processed, failed or unknown. It does not list messages sent from the Back Office or automations.

For how a purchase, its invoice and a discount code connect, see How invoices, items and discount codes connect.

For amount units, filters and side effects, see V2 workflows and field conventions.

Find the ID you need

Use IDs returned by the V2 resource you are referencing. A client ID identifies a client of the company, and a teacher ID identifies a teacher associated with that company. Do not substitute platform account IDs or V1 teacher IDs.

The following relationships have different discovery paths.

Required value Where to obtain it
class_id, class_ids /api/v2/management/classes/
client_class_pass_id /api/v2/management/client-class-passes/?client_ids=123
Appointment appointment_slot_id appointment_slot_ids on an appointment service, then /api/v2/management/appointment-slots/{id}/
teacher_id, venue_id, level_id /teachers/, /venues/, /levels/ under /api/v2/management/
Product base_product_id /api/v2/management/products/?type=base
Category identifiers Existing catalogue records expose category IDs, but V2 has no category directory endpoint. Obtain any additional category IDs from the company's configuration.
Subscription benefit with benefit_type=pack V2 exposes its identifier but has no pack detail endpoint.
Subscription pause_ids V2 exposes these identifiers but has no pause detail endpoint.

GET /clients/ already scopes results to X-Company-ID. Its company_id query filter only narrows those results; it does not switch companies. Omit it for the normal case. IDs represent whole-number identifiers even where a query parameter is described as a number.