billing

Kortix billing: plans (Free, Credits, Enterprise), credits and the wallet, compute and model pricing, trials, enterprise contracts, entitlement overrides and who may manage billing. Load before changi

SKILL.md

GitHub

Billing

The plan model and its lifecycle are specified in references/plans-and-access.md. Read it before you change billing code. Change the code and the spec together.

Rules

  • The plan alone decides features. Never add a flag that turns on part of a plan. Time-boxed access is a trial; an exception is an entitlement_overrides key.
  • One write path. Plan, trial, contract and override changes go through the audited admin routes in apps/api/src/admin/index.ts. Never write those columns with raw SQL in production.
  • Stripe never overwrites Enterprise. applyStripeSync skips tier writes on an Enterprise account; only activateEnterpriseContract and the contract end set or clear it.
  • Prices live in code once. Credits: billing/services/tiers.ts. Compute: platform/providers/compute-rates.ts, mirrored by packages/ui/src/internal/billing/compute-pricing.ts. Model fee: LLM_PLATFORM_FEE_PERCENT. Residential proxy: Platinum's charge, passed through (billing/services/residential-proxy-charges.ts). Storage: STORAGE_RATES_USD_PER_GIB_HOUR in compute-rates.ts, Platinum's volume and box disk prices × PLATINUM_MARKUP (billing/services/storage-charges.ts, box-disk-charges.ts).
  • Customers always see their state. A new plan state needs an account-state field and a visible label.

Where the code lives

Concern Code
Plan resolution (plan, trial, overrides, grace) apps/api/src/billing/services/resolve-billing.ts
Plans, prices, allowances apps/api/src/billing/services/tiers.ts
Enterprise contracts apps/api/src/billing/services/enterprise-contracts.ts
Trials apps/api/src/billing/services/trial-admin.ts
Warnings and expiry sweeps apps/api/src/billing/rotation-schedule.ts, worker/jobs/billing-rotation.ts
Stripe webhooks apps/api/src/billing/services/webhooks.ts, stripe-checkout-webhooks.ts
Account state API apps/api/src/billing/services/account-state.ts
Storage billing (volumes, stopped and archived box disks), Kortix's own unbilled cost apps/api/src/billing/services/storage-charges.ts, box-disk-charges.ts, orphan-box-costs.ts, worker/jobs/storage-billing.ts
Admin console apps/web/src/app/[locale]/admin/accounts/
Customer UI apps/web/src/features/billing/
Free credits once per person, the claimed workspace apps/api/src/billing/services/free-credit-claims.ts, free-grant.ts
Split-off billing (free, comped, comp end, reverse) apps/api/src/billing/services/split-off-billing.ts
Legacy Stripe recovery (no cross-workspace adoption) apps/api/src/billing/services/legacy-stripe-sync.ts