Trials

What is this

A trial is someone trying the studio out, and the coach running the class should know who they are. Trials makes them visible to that coach and closes the loop back to Sales. There is no “first workout” detection: a roster entry is a trial only when someone said so.

A rep schedules a lead’s trial into a class session from the Sales workspace. The trial holds a seat in that class like a booking does (see ADR-0025). When the lead converts before the class, the seat becomes their member booking.
A roster entry is a trial for one of three reasons, in precedence order: a Sales trial seat (or the booking it became on conversion), a staff mark on that booking, or a booking paid with a drop-in plan the owner flagged as a trial plan (e.g. a “Trial class”; only drop-in plans can be trial plans). The reason stays in the API: no client is told why someone is a trial, and coaches never see it.
Staff book an existing member as a trial (a paying one included) from the member page or a converted lead’s sheet: the member’s own booking through their plan, like any booking, marked as a staff trial.
Staff write notes on a lead or a member, flag the ones that matter as important, and see those on the roster and in the coach’s brief. Notes written on a lead follow the person after conversion.
The coach gets a push brief about an hour before a class with trials, and owners/admins/coaches see a Trials today card in the mobile app.
A coach’s check-in of a lead trial is evidence for Sales, not an outcome: the rep still confirms attended / no-show / cancelled, with attended preselected.

Who uses it

Persona	Why
Sales rep / manager	Picks a class for the trial (seats left shown), sees “Checked in HH:MM by ” on the lead, confirms the outcome. Writes lead notes. A trial converted before class reads “Converted — booked as member”.
Coach	Sees the roster with trials on top (flagged as trials, never why), important notes, health-declaration status and a phone/WhatsApp link, and for a lead trial the lead’s intake note; marks a booking as a trial (`canMarkTrial`) or unmarks a staff mark (`canUnmarkTrial`); checks people in; adds notes. Gets the brief push for the classes they coach.
Owner / Admin	Everything a coach can do, for every session; moderates any note; flags plans as trial plans.
Member	Nothing new. A lead’s trial seat is one fewer seat they can book.

Staff = membership role owner, admin or coach in the org. Coaches still have no Sales access; they reach lead trials only through the roster and its trial routes. Through the roster a coach does see a trialist’s name, phone and intake note (leads.note): that is intentional, so the coach can greet them knowing why they came. The lead source and who marked a booking are not exposed. Members never see the trial columns on their own bookings.

High-level capabilities

Trial seats — a lead trial appointment with a class_session_id that is pending or attended and not superseded counts against that session’s capacity everywhere bookings do, and makes the class not empty for bulk delete and template overwrite. Claimed race-safe. Ending a lead’s trial (reschedule, Not relevant, archive) frees the seat with a waitlist refill, unless the coach had checked the lead in: then the trial ends attended and keeps it. Converting the lead before the class moves the seat into their booking, in the conversion’s own transaction on every path. Cancelling, deleting or overwriting the class (or Arbox cancelling it) ends its trials too. See behavior › Trial seat lifecycle.
Who is a trial — lead seat > staff mark > trial plan per roster entry, API-internal. See behavior › Who is a trial.
Session roster — GET …/sessions/:id/roster, bookings and lead trial seats in one list.
Marking a trial — PUT …/sessions/:id/bookings/:bookingId/trial, staff. 4b. Member trial bookings — POST|GET …/members/:membershipId/trial-bookings (+ GET …/session-options), staff: book a member into a class through the normal booking engine with the staff mark; list their upcoming trials for any reason. See behavior › Booking a member as a trial.
Trial plans — the Trial workout kind in the plan editor, stored as a drop-in with plans.is_trial; optional “use within” window (expiresInDays) and one per person (trial_once_per_person, default on: a member self-serve purchase is refused with 409 trial_already_used to anyone who already held a trial plan of the org or has an unpaid checkout of another one; staff are never refused). A trial plan that was sold cannot be un-flagged (400 trial_plan_in_use). See behavior › Trial plans.
Lead trial check-in — evidence (checked_in_at, checked_in_by_user_id), undoable while pending; written to the lead’s Sales history.
Staff notes — on members and leads, with an important flag, carried over on conversion.
Health declaration state — signed / not_signed / null per roster entry.
Coach brief push — category trials, attempted once per session start time.
Trials today — the day’s sessions with live trials (mobile home card).

Surfaces

Client	Surface
Web — Sales	Trial result editor: class-session picker (date, time, class, coach, spots left; full classes disabled) or “Other (no class)” with a free time. Lead sheet: class, time, coach and check-in line per trial, “Converted — booked as member” for a converted one; notes section. Outcome editor preselects attended when checked in.
Web — Schedule	Session detail sheet reads the roster: “Trials · N” block on top (`SessionTrials`), a Trial badge (no reason), important notes, health chip, phone/WhatsApp, add note; “Mark as trial” (`canMarkTrial`) / “Unmark” (`canUnmarkTrial`) on booking rows; lead trials check in / undo through the trial routes. Today panel shows a trial count per session.
Web — Plans	Plan editor Trial workout kind (after Drop-in) with only the trial fields; plans list and plan header read “Trial workout”.
Web — Member purchase	Shop, add-child plan step and the join page explain `trial_already_used`.
Web — Members	Member detail overview carries the same notes component (`StaffNotes`) and a Trial classes card: upcoming trials (Unmark on staff marks) and Book trial class (class picker, plan picker when several plans can pay). A converted lead’s Sales sheet shows the same card for the member.
Mobile (staff)	Home “Trials today” card; Roster section on the session screen with mark / unmark, check-in / undo and add note; `trials` push opens the session (switching org when needed).

Relationship to other features

leads-crm / Sales workspace — trial appointments, outcomes and the lead activity ledger live there; Trials adds the class seat, its move into a booking on conversion, and the check-in evidence.
scheduling-bookings — capacity, waitlist promotion (trial_released trigger), the entitlement sweep and the session time-change event.
subscriptions-plans — the is_trial / trial_once_per_person plan fields and the member purchase path the once-per-person rule guards.
forms — the health-declaration compliance form (type_key = 'health_declaration').
push-notifications — trials category.
Mobile architecture — the staff surfaces in the app.

Current status

Shipped, no feature flag: seat logic only engages when a rep picks a session, plan trials only when an owner flags a plan, and the coach surfaces are additive.

Known gaps

Ending a class’s trials on cancel/delete runs no waitlist (the class is gone) and sends the lead nothing; the rep sees the sales_trial activity and the lead without a next action in the queue.
The auto no-show job never marks lead trials; a trial without a recorded outcome stays in the Sales queue as outcome work.
A converted trial’s booking is paid by a plan only when exactly one of the member’s plans can pay (a trial plan breaks a tie); otherwise it carries no plan.
Notes are plain text; no mentions or attachments.