Billing & Subscription

platform-api owns the whole money path: plans define what you sell, a subscription (via PayPal) grants credits into a per-user wallet, and those credits are spent by relay when the user runs internal AI. This page covers the user-facing endpoints, the subscription lifecycle, credits/quota, and the admin surface.

The pieces

User endpoints

All require a PAT or Clerk JWT and are @Roles('user', 'admin').

Start a subscription

POST /api/billing/subscriptions
{ "planId": "plan_xxx", "channel": "paypal" }

channel defaults to paypal (the only enabled channel today). The response is { "approveUrl": "https://www.paypal.com/..." } — redirect the user there. A local Subscription row is created in pending; if the PayPal call fails it is rolled back so no orphan remains. An existing effective subscription (pending / active / past_due) returns 409.

Read entitlement

GET /api/billing/ai-entitlement is the single source the resume app reads to decide whether internal AI is available:

{
  "mode": "internal",              // or "byok_required"
  "canUseInternal": true,
  "reason": null,                   // daily_quota_exhausted | weekly_quota_exhausted | no_balance | no_active_subscription
  "balanceCredits": "1250000",
  "currency": "USD",
  "currentPlan": { "dailyLimit": 50, "weeklyLimit": 200, "modelAllowlist": [] },
  "availableModels": ["gpt-5.6", "claude-opus-4-8"],
  "usage": { "dailyUsed": 3, "weeklyUsed": 12, "dailyResetAt": "…", "weeklyResetAt": "…" }
}

canUseInternal is true only when balance > 0 and the plan’s day/week caps aren’t exhausted. With no active subscription it falls back to the default free plan (isDefault, priceCents: 0). availableModels is the admin-curated set of enabled models, narrowed by the plan’s modelAllowlist (empty = full catalog).

Subscription lifecycle

Payment webhook

POST /api/webhooks/paypal   (@Public)

Lives under the /api/webhooks/* prefix, which preserves the raw request body for signature verification. The handler verifies the PayPal signature, then records the PaymentEvent idempotency marker and applies the side effect in one transaction — if dispatch fails, the marker rolls back too, so PayPal’s retry reprocesses cleanly instead of losing the grant. A duplicate event returns { ok: true, duplicate: true }.

Credits & the wallet

• GET /api/billing/wallet → { balanceCredits, currency, recent[] } (recent CreditTransactions).
• Credits enter via subscription grants; they leave when relay reserves then settles the real token cost of an AI request; admins can adjust manually.
• The wallet is authoritative and every movement is a CreditTransaction — the ledger reconciles against relay’s UsageLedger.

AI quota (day / week caps)

Beyond raw balance, a plan can cap dailyLimit / weeklyLimit internal AI calls (0 = unlimited). Windows are computed in UTC (ISO week starts Monday 00:00) so resets are deterministic across instances. The counters (AiQuotaCounter) are written by atomic reservations in agent-service, not here — this service only reads them for entitlement. Over-limit blocks internal AI regardless of balance and surfaces as daily_quota_exhausted / weekly_quota_exhausted.

Admin endpoints

All @Roles('admin') (RBAC defaults to admin when a role isn’t specified).