Billing

The billing module answers one question for the rest of the backend: what plan is this studio on, and does it have room for one more trainee or team member. It has a single HTTP endpoint that reports the plan and usage. Most of the module is a guard that other modules call before they write. Checkout, plan changes, seat changes and the customer portal are not in this module. They are oRPC procedures in packages/api/src/modules/payments/procedures/ (create-checkout-link, change-subscription, set-seats, create-customer-portal-link, list-purchases), not Express routes under /v1.

Mount point and auth

Lane	Base path	Middleware
Web gateway	`/v1/web/billing`	`requireServiceAuth`, `webUserContext`, web rate limiter

Source: apps/core-api/src/modules/billing/. The router has no role guard. Any staff role can read the plan. The response tells the client whether the viewer may change it (canChange).

`GET /v1/web/billing/plan`

Returns the studio’s plan, its limits and current usage. Auth: web lane, any role. There are no parameters.

string

solo when there is no paid purchase, otherwise the purchased or granted plan id from the catalog in packages/payments/src/config.ts. A purchase on a product outside the catalog reads as custom.

string

none (no paid purchase), manual (granted from the admin panel, nothing billed) or billed (a Polar subscription).

string | null

The purchase status from the provider, for example active or trialing. null without a purchase.

object

trainees and includedSeats. Each is a number or null for no cap.

integer | null

Team seats the studio may fill, the coach included. On a seat-priced subscription this is the provider’s seat count, never fewer than the plan includes. Otherwise it is the plan’s includedSeats. null means no cap, either because the plan is unlimited or because the provider could not be reached.

object

Show usage

integer

Clients with deletedAt null and status other than ARCHIVED, minus the coach’s own trainee row when one is found.

integer

Active Coach rows. The owner and pending invites are included.

integer

Active Coach rows with no externalUserId, meaning the invite has not been claimed.

boolean

A grandfathered subscription on its old product and price.

boolean

true when the studio is billed on a seat-priced product, so seats can change through the set-seats procedure.

boolean

true when the caller’s role is OWNER or HEAD_COACH.

boolean

true when all three hold: the studio finished the /start wizard (settings.onboarding.completedAt is set), it has no paid plan (source is none), and it holds more than the free plan allows (trainees over limits.trainees, or coaches over seats). The web app keeps the owner on the plan screen, or on the team page to cancel invites, until this is false. Studios created before the wizard wrote its finish stamp never get it.

{
  "ok": true,
  "data": {
    "planId": "grow",
    "source": "billed",
    "status": "active",
    "limits": { "trainees": 50, "includedSeats": 2 },
    "seats": 3,
    "usage": { "trainees": 41, "coaches": 3, "pendingInvites": 1 },
    "isLegacyPrice": false,
    "seatsAdjustable": true,
    "canChange": true,
    "planChoiceRequired": false
  },
  "requestId": "5f6a7b8c-9d0e-4f1a-b2c3-d4e5f6a7b8c9"
}

Errors: UNAUTHORIZED (401) authentication required. The seat lookup fails open, so a provider outage does not turn into an error here.

Plan catalog limits

From packages/payments/src/config.ts. Every paid plan includes the coach plus one team member.

Plan id	Trainees	Included seats
`solo` (free)	5	1
`start`	25	2
`grow`	50	2
`pro`	100	2
`elite`	250	2
`enterprise`	500	2
`custom`	no cap	no cap

How the plan is resolved

createStudioPlanResolver in billing.plan.ts returns a StudioPlan.

repo.purchasesOf(studioId) loads the Purchase rows of the studio’s organization (Studio.externalOrgId), oldest first.
resolveStudioPlanPurchase from @repo/payments picks the deciding row. An admin grant wins. Next is a billed subscription that is not a hidden add-on, with a catalog product preferred over an unknown one. With neither, the studio is on the free plan. Purchase status is not read: a revoked subscription has no row because the webhook deletes it.
No purchase: planId is solo with the free limits.
A purchase on a product the catalog does not know: planId is custom, no limits, seats is null. A warning is logged once per price id per process.
A catalog plan that is not seat-priced (a grant, a legacy price, or a price with no seatAmount): seats is the plan’s includedSeats.
A seat-priced subscription: seats are read from the provider and floored at the plan’s included seats.

Callers that only need the trainee cap pass { seats: false } so they never wait on the provider.

Seat lookup and cache

Seats live on the Polar subscription. There is no database column. billing.seats.ts reads them on demand.

Constant	Value	Meaning
`SEAT_CACHE_TTL_SECONDS`	600	Redis TTL per subscription snapshot
`CACHE_WAIT_MS`	300	Deadline for a Redis read or write
`PROVIDER_WAIT_MS`	5000	Deadline for the provider call
`SEAT_LOOKUP_RETRY_MS`	60000	After a failed lookup, the subscription is not asked again for this long, per process

The Redis key is perform:billing:subscription: followed by the subscription id. The reader returns { known: false } when the provider cannot answer, and the caller then does not enforce seats. A provider outage costs one wait per retry window, not one per request. installBillingSeatCache(ctx) is called once in server.ts. It subscribes to onSubscriptionChange from @repo/payments, so every subscription webhook and every plan or seat change seen in this process rewrites the cache at once. A revoked change deletes the entry. A snapshot older than the cached one (by modifiedAt) is ignored, because webhooks can arrive out of order.

Plan limit guards

billingFor(ctx) in billing.wiring.ts builds one shared set per app context: repo, getStudioPlan, limits and service. Other routers take billingFor(ctx).limits.

Function	What it does	Lock
`traineeCapacity(studioId)`	Returns `planId`, `limit`, `count`, `remaining`. All `null` except `planId` on an unlimited plan.	None
`assertCanAddTrainees(studioId, adding = 1)`	Throws when `count + adding` exceeds the limit. For single-click writes such as un-archiving.	None
`withTraineeRoom(studioId, adding, write)`	Counts and runs `write` in one transaction holding the studio’s trainee lock. Used for creates. An unlimited plan takes no lock and calls `write()` with no transaction.	`trainees`
`assertCanAddCoach(studioId)`	Throws when the team is full. For bringing a dismissed member back.	None
`withSeat(studioId, write)`	Counts and runs `write` (an invite) under the studio’s seat lock.	`seats`
`isOnboarding(studioId)`	`true` while the studio is still in the `/start` wizard.	None

The lock is pg_advisory_xact_lock(hashtext('perform:billing:' + scope + ':' + studioId)) inside a Prisma transaction with a 15 second timeout (LOCK_TRANSACTION_TIMEOUT_MS). It makes parallel creates queue, so imports and automation webhooks cannot all pass a count taken before any of them wrote.

Who calls them

Caller	Guard
`modules/clients/clients.service.ts`	`withTraineeRoom` on create, `assertCanAddTrainees` on un-archive
`modules/coaches/coaches.service.ts`	`withSeat` on invite, `assertCanAddCoach` on reactivation
`modules/crm/crm.routes.ts`	Passes `limits` to the CRM service for lead conversion. See CRM.
`modules/automation-api/automation-api.routes.ts`	Passes `limits` for trainee creates through the API key lane
`modules/onboarding/onboarding.service.ts`	`isOnboarding` to exempt the wizard, and `planLimitDetailsOf` to read a refusal. See Onboarding.

What counts

Trainees. Client rows with deletedAt null and status other than ARCHIVED. The coach’s own trainee row, created by the /start bootstrap, is never counted. Nothing marks that row, so selfClientIdOf matches it on the last 9 digits of the owner’s coach phone, then on the owner’s email, oldest match first.
Team. Active Coach rows, including the owner and unclaimed invites.

The onboarding exemption

isOnboarding is true when settings.onboarding.bootstrappedAt is set, settings.onboarding.completedAt is not, and the studio was created less than ONBOARDING_WINDOW_MS ago. That constant is STUDIO_ONBOARDING_WINDOW_MS from @perform/types: 72 hours. Only server-written state is read. Seat checks are skipped while it is true, because invites sent from the wizard come before the plan choice. Trainee checks in withTraineeRoom and assertCanAddTrainees do not consult it. The onboarding service applies its own exemption for the wizard import.

The refusal

A studio already over its plan keeps everything it has. It only cannot add more. A refusal is an AppError with code FORBIDDEN (403) and a details object the web app uses to open its upgrade dialog:

{
  "ok": false,
  "code": "FORBIDDEN",
  "message": "The studio's plan holds up to 5 trainees and 5 are active. Upgrade the plan to add more.",
  "details": {
    "reason": "PLAN_LIMIT_TRAINEES",
    "limit": 5,
    "count": 5,
    "planId": "solo"
  },
  "requestId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

reason is PLAN_LIMIT_TRAINEES or PLAN_LIMIT_SEATS. The message is a full sentence because the automation lane shows it to the coach as is. planLimitDetailsOf(error) returns the details for a plan refusal and null for any other error.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Mount point and auth

`GET /v1/web/billing/plan`

Plan catalog limits

How the plan is resolved

Seat lookup and cache

Plan limit guards

Who calls them

What counts

The onboarding exemption

The refusal

​Mount point and auth

​GET /v1/web/billing/plan

​Plan catalog limits

​How the plan is resolved

​Seat lookup and cache

​Plan limit guards

​Who calls them

​What counts

​The onboarding exemption

​The refusal

Mount point and auth

`GET /v1/web/billing/plan`

Plan catalog limits

How the plan is resolved

Seat lookup and cache

Plan limit guards

Who calls them

What counts

The onboarding exemption

The refusal