Skip to main content

Source: ocean/docs/adr/0022-billing-trial-and-seat-management.md | ✏️ Edit on GitHub

ADR-0022: Billing Seat Management via GraphQL (No Trials)

Date: 2025-08-13

Status: Accepted

Context​

We require a simple onboarding: all organizations are Free until they upgrade. Trials are not used. Team plan has a small fixed cap to keep onboarding simple; seat control happens after provisioning on the billing page.

Decision​

  • Remove trials entirely; no startTrial mutation or trial UI states. "Free until upgrade" is the policy.
  • Implement seat management for Team via GraphQL mutation updateSubscription({ priceId, quantity }).
  • Seat cap: Team seats are limited to 5.
    • UI: show seat control on billing page with min=1 and max=5.
    • Server: validate/clamp quantity to [1..5].
    • Enforcement: member invites/role changes must not exceed seat count.
  • Use GraphQL for all app-initiated billing changes; webhooks are for out-of-band reconciliation only.

Consequences​

  • Users get provisioned fast on Free; they can later upgrade to Pro or Team and set seats (up to 5) from billing.
  • Reduced complexity by avoiding trial code paths and timers.
  • Predictable plan/seat behavior with server enforcement.

Notes​

  • Env: STRIPE_PRO_PRICE_ID, STRIPE_TEAM_PRICE_ID.
  • Add DB or resolver checks to prevent invites beyond seats.