Payments, billing and plan limits

Two different things are called a subscription in this codebase. Keep them apart.

Subscription	Who pays whom	Code
Studio plan	The studio pays Perform	`@repo/payments`, `@repo/api` payments procedures, `modules/billing/`
Trainee subscription	The trainee pays the studio. Perform only records it.	`modules/client-subscriptions/`, `modules/products/`

This page is about the first. Trainee subscriptions involve no payment provider.

Pieces

@repo/payments holds the plan catalog, the provider and the plan resolution helpers.
@repo/api exposes the billing actions to the web app as oRPC procedures.
apps/core-api/src/modules/billing/ reads the result and enforces limits on domain writes.

The plan catalog

packages/payments/src/config.ts is the catalog. Billing is attached to the organization (billingAttachedTo: 'organization') and an active subscription is not required (requireActiveSubscription: false).

Plan id	Trainee limit	Included seats	Monthly price (ILS)	Notes
`solo`	5	1	0	The free plan. `FREE_PLAN_ID`.
`start`	25	2	300
`grow`	50	2	450	`recommended`
`pro`	100	2	900
`elite`	250	2	1500
`enterprise`	500	2	2000	Directly purchasable.
`custom`	none	none	sales led	`isEnterprise`. Granted by an admin. `CUSTOM_PLAN_ID`.
`teamSeat`			49	Hidden legacy add-on. Never a studio’s plan.

Every base plan is the full product. Plans differ only by limits. Rules encoded in the config:

Each paid plan has two prices. The first is the current one: a fixed fee plus a seat price of 49 for every seat beyond the included ones (seatAmount). The second has legacy: true: the fixed price product sold before the seat model. A legacy price still resolves an existing purchase to its plan and is never sold again.
priceId values are Polar product ids. Current ones can be overridden with PRICE_ID_<PLAN>_V2, legacy ones come from PRICE_ID_<PLAN>_MONTHLY.
Trials are configured on the Polar products. trialPeriodDays: 30 in the config is display only.
solo is a real Polar product whose price sits behind a trial that does not end, so its checkout stores a card and never charges. A studio with no purchase at all is also on solo.
TODO_POLAR_ID is the prefix of a product id that was never filled in. isPlaceholderProductId stops such an id from reaching Polar.

monthlyTotal(planId, price, seats) computes what a team pays: the fixed amount plus max(0, seats - includedSeats) * seatAmount.

Purchase rows

A studio’s billing state is the Purchase rows of its organization (auth schema). Seats are not stored. They live on the Polar subscription. resolveStudioPlanPurchase(purchases) in lib/studio-plan.ts picks the row that decides the plan:

An admin grant wins. A grant is a SUBSCRIPTION row whose customerId is MANUAL_PURCHASE_CUSTOMER_ID (admin:manual).
Otherwise a billed subscription that is not on a hidden plan. One on a catalog product wins over one on a product the catalog does not know.
Otherwise the studio is on the free plan, with source: 'none'.

Status is not read. A revoked subscription has no row, because the webhook deletes it. The result is one of three sources: none, manual, billed.

The Polar provider

packages/payments/src/provider/index.ts exports the Polar implementation. A Stripe implementation exists in provider/stripe/ and is not exported.

Export	Purpose
`createCheckoutLink(params)`	Creates a hosted checkout. Sends `organization_id` and `user_id` as metadata and optional `seats`, `minSeats`, `maxSeats`.
`createCustomerPortalLink({ customerId })`	Customer portal session URL.
`getSubscription(id)`	A `SubscriptionSnapshot`: `id`, `productId`, `seats`, `status`, `modifiedAt`.
`updateSubscription({ id, productId?, seats?, prorationBehavior, trialEnd? })`	Polar takes one kind of change per update, so a product switch and a seat change are two requests, product first. Publishes the change.
`setSubscriptionSeats({ id, seats })`	Sets seats only.
`cancelSubscription(id)`	Revokes the subscription.
`webhookHandler(request)`	The webhook endpoint.
`getPolarClient()`	The SDK client. Server is `sandbox` when `POLAR_SERVER` is `sandbox`, otherwise production.

The webhook

POST /api/webhooks/payments is routed by the Hono app to webhookHandler. The gateway forwards the raw body, which the signature needs.

A missing POLAR_WEBHOOK_SECRET answers 500.
validateEvent(body, headers, secret) verifies the signature. A failure answers 400.
The event is handled:

Event	Effect
`subscription.created`	Publishes the snapshot. If the product is in the catalog and no purchase exists for this subscription id, creates a `SUBSCRIPTION` purchase from the checkout metadata and stores the Polar customer id on the organization or user.
`subscription.updated`	Publishes the snapshot. Updates the purchase’s `status` and `priceId`.
`subscription.revoked`	Publishes a revoke. Deletes the purchase if it still exists.
`order.created`	Ignored for subscription orders. A true one time order creates a `ONE_TIME` purchase.

Design points:

An unknown product is acknowledged with 200. A 4xx would make Polar redeliver forever.
Redeliveries are idempotent. subscriptionId is unique and an existing row short circuits the create.
The revoke can arrive after the row is already gone, when the organization was deleted first.

Subscription change events

lib/subscription-events.ts is an in-process publish and subscribe list stored on globalThis under a symbol, so every copy of the module shares it.

export type SubscriptionChange =
  | { kind: 'updated'; subscription: SubscriptionSnapshot }
  | { kind: 'revoked'; subscriptionId: string };

onSubscriptionChange(listener);         // returns an unsubscribe function
await publishSubscriptionChange(change); // a failing listener is logged, never thrown

The webhook and updateSubscription publish. installBillingSeatCache(ctx), called once in server.ts, subscribes and writes the snapshot into the seat cache. This works because the webhook handler and core-api run in the same process.

Reading a studio’s plan in core-api

billingFor(ctx) returns one shared set per AppContext:

const { repo, getStudioPlan, limits, service } = billingFor(ctx);

getStudioPlan(studioId, options?) returns a StudioPlan:

Field	Meaning
`planId`	`solo` without a paid purchase, else the purchased or granted plan. A purchase on a product outside the catalog reads as `custom`, with no limits.
`source`	`none`, `manual` or `billed`.
`status`	The purchase status from Polar, or null.
`limits`	`{ trainees, includedSeats }`, each null when there is no cap.
`seats`	Seats the studio may fill, coach included. On a seat priced product it is the subscription’s seats, never fewer than the plan includes. Otherwise the plan’s included seats. Null means no cap.
`isLegacyPrice`	The studio is on a grandfathered price.
`seatsAdjustable`	Billed on a seat priced product.
`subscriptionId`	Present for a billed plan.

Pass { seats: false } when you only need the trainee limit. That skips the seat lookup, so a trainee write never waits on Polar.

The seat cache

billing.seats.ts. Seats are read on demand and cached.

Setting	Value
Key	`perform:billing:subscription:<subscriptionId>`
TTL	600 seconds
Redis read deadline	300 ms
Polar call deadline	5,000 ms
Retry after a failed lookup	60 seconds, per process

The cache is rewritten by every subscription webhook and every plan or seat change, so a purchase shows up at once. If Polar cannot be reached the lookup returns “unknown” and the seat limit is not enforced. Billing must never block a studio from working.

Enforcing limits

limits is the guard described on Roles and permissions. The locking detail:

SELECT pg_advisory_xact_lock(hashtext('perform:billing:<scope>:<studioId>'))

withStudioLock(studioId, scope, fn) opens a transaction, takes a Postgres advisory lock for the scope (trainees or seats), and runs the count and the write inside it. Parallel creates for the same studio queue behind the lock, so none of them passes a count taken before another wrote. The lock is released when the transaction ends. The routers that pass billingFor(ctx).limits into their services are the ones that create trainees or team members: clients, coaches, crm (convert a lead), onboarding (the import after /start) and automation-api. What counts:

Trainees: not deleted, not archived, and the coach’s own trainee row is excluded (ownerOf).
Team: active Coach rows, which includes the owner and people invited who have not signed in yet.

`GET /v1/web/billing/plan`

The one billing endpoint in core-api. Any staff role can read it. It returns a BillingPlanSummary:

{
  "planId": "start",
  "source": "billed",
  "status": "active",
  "limits": { "trainees": 25, "includedSeats": 2 },
  "seats": 3,
  "usage": { "trainees": 18, "coaches": 3, "pendingInvites": 0 },
  "isLegacyPrice": false,
  "seatsAdjustable": true,
  "canChange": true,
  "planChoiceRequired": false
}

canChange is true for OWNER and HEAD_COACH.
planChoiceRequired is true when the studio finished the /start wizard, has no paid plan, and holds more trainees or team members than the free plan allows. The web app keeps the owner on the plan screen until it is false.

Changing a plan

Changes go through the oRPC payments router in @repo/api, not through /v1:

Procedure	Purpose
`createCheckoutLink`	Start a checkout for a plan. Refused when the organization already has a billed subscription.
`changeSubscription`	Switch plan on an existing subscription.
`setSeats`	Change the seat count. Never below the active team.
`createCustomerPortalLink`	Open the Polar customer portal.
`listPurchases`	The organization’s purchase rows.

Guards in modules/payments/lib/billing.ts:

requireOrganizationMember and requireBillingManager: only organization roles owner and admin may change billing.
SELF_SERVE_PLAN_IDS: start, grow, pro, elite, enterprise.
MAX_TEAM_SEATS is 100. Beyond that is a sales conversation.
teamSeatFloor and teamSeatsFor: seats are never set below the number of active coaches, and never below 1.

A refusal is an ORPCError whose data.reason is one of NO_SUBSCRIPTION, MANUAL_PLAN, UNKNOWN_PLAN, LEGACY_PLAN, NOT_CONFIGURED, PROVIDER_ERROR, HAS_SUBSCRIPTION, PLAN_LIMIT_TRAINEES. Billing never follows the team on its own. Seats on a subscription change only when a manager sets them.

Admin grants

A platform admin can give a studio a plan without billing through the admin.studios.setPlan procedure, which calls setAdminStudioManualPlan. The grant is a purchase row with customer id admin:manual. A grant of the custom plan stores the sentinel product id admin:custom (CUSTOM_GRANT_PRICE_ID), because that plan has no Polar product.

What happens on delete

beforeOrganizationDelete and beforeUserDelete in @repo/auth cancel billed subscriptions with cancelSubscription before the rows go. An admin grant has no subscription behind it and simply cascades.

Env

POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, POLAR_SERVER, the PRICE_ID_*_V2 overrides, the legacy PRICE_ID_*_MONTHLY ids and PRICE_ID_TEAM_SEAT. They are read with process.env inside the package. A missing access token throws on the first Polar call, not at boot.

​Pieces

​The plan catalog

​Purchase rows

​The Polar provider

​The webhook

​Subscription change events

​Reading a studio’s plan in core-api

​The seat cache

​Enforcing limits

​GET /v1/web/billing/plan

​Changing a plan

​Admin grants

​What happens on delete

​Env