@repo/payments

packages/payments knows the plan catalog and talks to the payment provider. It does not know about studios, trainees or limits enforcement. That is modules/billing in core-api. The end to end flow is on Billing and plan limits. src/index.ts exports:

export { TODO_POLAR_ID } from './config';
export * from './lib/customer';
export * from './lib/plans';
export * from './lib/provider-price-ids';
export * from './lib/studio-plan';
export * from './lib/subscription-events';
export * from './provider';
export * from './types';

The catalog object itself (config) is not exported. Consumers go through the helpers.

Types (`types.ts`)

Type	Shape
`PlanPrice`	A `BasePrice` (`amount` in major units, `currency`, optional `priceId`) combined with either a `SubscriptionPrice` or a `OneTimePrice`.
`SubscriptionPrice`	`type: 'subscription'`, `interval` (`month` or `year`), optional `seatBased`, `seatAmount`, `legacy`, `trialPeriodDays`.
`OneTimePrice`	`type: 'one-time'`.
`PlanLimits`	`trainees` and `includedSeats`, each a number or `null` for no cap.
`PaidPlan`	`prices`, optional `limits`, `recommended`, `hidden`.
`EnterprisePlan`	`isEnterprise: true`, optional `limits`, `recommended`, `hidden`.
`FreePlan`	`isFree: true`, `limits`, optional `prices`, `recommended`, `hidden`.
`Plan`	Union of the three.
`PaymentsConfig`	`billingAttachedTo`, `requireActiveSubscription`, `plans`.
`SubscriptionSnapshot`	`id`, `productId`, `seats`, `status`, `modifiedAt`. The slice of a provider subscription the app acts on.
`ProrationBehavior`	`invoice`, `prorate`, `next_period`, `reset`.
Provider function types	`CreateCheckoutLink`, `CreateCustomerPortalLink`, `SetSubscriptionSeats`, `GetSubscription`, `UpdateSubscription`, `CancelSubscription`, `WebhookHandler`, and `PaymentProvider`.

Money in this package is in major currency units (300 means 300 ILS). Domain prices for trainee plans are stored in agorot (priceAgorot). Do not mix the two.

Plans (`lib/plans.ts`)

Export	Purpose
`PlanId`	Union of the catalog’s plan keys.
`RecurringInterval`	`month` or `year`.
`FREE_PLAN_ID`	`solo`. Not `free`, which the purchases helper uses for “no purchase at all”.
`CUSTOM_PLAN_ID`	`custom`.
`CUSTOM_GRANT_PRICE_ID`	`admin:custom`, the product id stored on an admin grant of the custom plan.
`getPaidPlan(planId)`	The plan when it has prices, else null.
`isFreePlan(planId)`	True for a plan with `isFree`.
`getPlanLimits(planId)`	The plan’s limits, or null for a plan that has none (an add-on).
`findPriceByPlanId(planId, { type, interval })`	The price that is sold: the first non legacy price of that type and interval.
`isPlaceholderProductId(priceId)`	True for an empty id or one starting with `TODO_POLAR_ID`.
`monthlyTotal(planId, price, seats)`	Fixed amount plus seats beyond the included ones times `seatAmount`. Fixed price products ignore seats.

Provider ids (`lib/provider-price-ids.ts`)

Export	Purpose
`getProviderPriceIdByPlanId(planId, selection)`	The provider id of the price that is sold. Never a legacy one.
`getPlanIdByProviderPriceId(priceId)`	The plan a provider id names. The custom grant sentinel names `custom`. Null for an unknown id.
`getPlanPriceByProviderPriceId(priceId)`	`{ planId, price }` for an id. A legacy id resolves to its legacy price, so a grandfathered purchase shows what it is charged.
`isLegacyProviderPriceId(priceId)`	True for a plan’s grandfathered price.

Despite the name, a “price id” here is a Polar product id.

Studio plan resolution (`lib/studio-plan.ts`)

Export	Purpose
`PlanPurchase`	The purchase fields the resolver reads: `id`, `type`, `customerId`, `priceId`, `status`, `subscriptionId`.
`StudioPlanPurchase`	Discriminated on `source`: `none` (free plan, no purchase), `manual` (admin grant) or `billed`.
`isManualPurchase(purchase)`	`customerId` equals `MANUAL_PURCHASE_CUSTOMER_ID`.
`billedPlanPurchases(purchases)`	Subscriptions that can decide a plan: not grants, not the hidden seat add-on.
`resolveStudioPlanPurchase(purchases)`	The purchase that decides the studio’s plan, with `planId`, `price` and `isLegacyPrice`.

planId can be null on a billed purchase whose product is not in the catalog. The caller decides what that means. core-api reads it as the custom plan with no limits.

Purchases helper (`lib/helper.ts`)

The file exports createPurchasesHelper(purchases), returning { activePlan, hasSubscription, hasPurchase }, and the ResolvedPurchase type. It is not re-exported from the package index. It predates the studio plan resolver and treats “no purchase” as plan id free when requireActiveSubscription is false. Use resolveStudioPlanPurchase for anything about a studio’s plan.

Customer link (`lib/customer.ts`)

Export	Purpose
`setCustomerIdToEntity(customerId, { organizationId?, userId? })`	Stores the provider customer id on the organization, or on the user when there is no organization.
`getCustomerIdFromEntity({ organizationId } \| { userId })`	Reads it back.

Subscription change events (`lib/subscription-events.ts`)

Export	Purpose
`SubscriptionChange`	`{ kind: 'updated', subscription }` or `{ kind: 'revoked', subscriptionId }`.
`onSubscriptionChange(listener)`	Subscribe. Returns an unsubscribe function.
`publishSubscriptionChange(change)`	Calls every listener in turn. A listener that throws is logged and never fails the caller.

The listener set lives on globalThis under Symbol.for('perform.payments.subscriptionChangeListeners'), so two copies of the module loaded through different paths still share it.

Provider (`provider/`)

provider/index.ts re-exports ./polar.

Export	Notes
`getPolarClient()`	Throws `Missing env variable POLAR_ACCESS_TOKEN` when the token is unset.
`createCheckoutLink(params)`	Returns the checkout URL or null. Polar rejects empty metadata values, so only set ids are sent.
`createCustomerPortalLink({ customerId })`	Returns the portal URL or null.
`setSubscriptionSeats({ id, seats })`
`getSubscription(id)`	Returns a snapshot.
`updateSubscription(params)`	Product first, then seats. Throws when neither is given. Publishes an `updated` change.
`cancelSubscription(id)`	Calls Polar’s revoke.
`subscriptionSnapshot(subscription)`	Maps a Polar subscription to `SubscriptionSnapshot`.
`webhookHandler(request)`	Verifies and handles `subscription.created`, `subscription.updated`, `subscription.revoked` and `order.created`.

provider/stripe/index.ts implements the same function types against Stripe. It is in the tree and not exported. Switching provider means changing the one export line, supplying the Stripe env and reviewing every place that assumes Polar’s product based ids and seat model.

Tests

lib/catalog.test.ts checks the catalog and the lookup helpers. provider/polar/polar.test.ts covers the provider.

Changing the catalog

Edit src/config.ts. Keep the current price first and the legacy price second for each paid plan.
Create the Polar product and supply its id through the matching env variable.
Never remove a legacy price while a studio still holds a purchase on it. The purchase would stop resolving to a plan and the studio would read as custom, with no limits.
Rebuild with pnpm --filter @repo/payments build. Both @repo/api and core-api read the package from dist.
If the web app keeps its own copy of the catalog for its pricing screens, update it there too.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Types (`types.ts`)

Plans (`lib/plans.ts`)

Provider ids (`lib/provider-price-ids.ts`)

Studio plan resolution (`lib/studio-plan.ts`)

Purchases helper (`lib/helper.ts`)

Customer link (`lib/customer.ts`)

Subscription change events (`lib/subscription-events.ts`)

Provider (`provider/`)

Tests

Changing the catalog

​Types (types.ts)

​Plans (lib/plans.ts)

​Provider ids (lib/provider-price-ids.ts)

​Studio plan resolution (lib/studio-plan.ts)

​Purchases helper (lib/helper.ts)

​Customer link (lib/customer.ts)

​Subscription change events (lib/subscription-events.ts)

​Provider (provider/)

​Tests

​Changing the catalog

Types (`types.ts`)

Plans (`lib/plans.ts`)

Provider ids (`lib/provider-price-ids.ts`)

Studio plan resolution (`lib/studio-plan.ts`)

Purchases helper (`lib/helper.ts`)

Customer link (`lib/customer.ts`)

Subscription change events (`lib/subscription-events.ts`)

Provider (`provider/`)

Tests

Changing the catalog