Billing

On This Page

How A Subscription Comes To LifeCheckout creates the session; webhooks write the Subscription row.Package LayoutWhere the catalog, Stripe wrapper, procedures, and UI live.What's Wired InCheckout, portal, phases, gates, limits, emails, and tax.Pricing Plans And CatalogBaseline, plans, prices, features, limits, and the knobs you can tune.Subscription PhasesSeven BillingPhase values: free, paywalled, entitled, grace, recoverable, lapsed, error.Checkout And PortalcreateCheckout, createPortal, and the dashboard billing page.Payment Methods And TaxDashboard-driven methods and opt-in Stripe Tax.The Webhook PathWhich Stripe events the kit handles and how idempotency works.Entitlements And GatingRead BillingState, then gate features and limits from your code.Customizing The CatalogWorked example: add a Team tier end to end.

How A Subscription Comes To Life

Two halves:

1. Sync. The dashboard calls billing.createCheckout. The user pays on Stripe-hosted Checkout. On return, a query param drives a success/cancel toast.
2. Async. Stripe webhooks report what actually happened. processWebhookEvent claims the event id (retries are no-ops), upserts Subscription, syncs Organization.currentSubscriptionId, and sends email/analytics through OutboundEffect (each side effect at most once). The next getBillingState read resolves to entitled.

Subscriptions are org-scoped, not user-scoped. Card details never touch your domain. Polar and LemonSqueezy adapters are on the roadmap; BillingState and entitlements are already provider-agnostic.

Package Layout

What's Wired In

Pricing Plans And Catalog

One TypeScript object in packages/payments/src/catalog/declaration.ts, built with defineBillingCatalog. Two parts (ADR 0002):

• baseline (optional). What an org with no active subscription gets.
• plans. Purchasable tiers.

Each price points at a server-only env var (stripePriceEnv) that holds the Stripe price ID. The ID is never written in the catalog file or shipped to the client.

The catalog shape

export const billingCatalogDeclaration = defineBillingCatalog({
  // The unsubscribed floor. `visibleAsPlan: true` renders it as a card.
  // Omit `baseline` entirely to run a hard paywall (see "Paid-only" below).
  baseline: {
    name: "Free",
    description: "Get started without a credit card",
    visibleAsPlan: true,
    entitlements: {
      features: createBillingFeatureFlags(),
      limits: { maxMembers: 3, monthlyAiResponses: 100 },
    },
  },
  // The purchasable tiers. `PlanSlug` is derived from these keys.
  plans: {
    pro: {
      name: "Pro",
      description: "For teams shipping AI features",
      recommended: true,
      prices: [
        {
          interval: "month",
          amount: 29, currency: "USD", trialDays: 7,
          stripePriceEnv: "STRIPE_PRICE_ID_PRO_MONTHLY",
        },
        {
          interval: "year",
          amount: 290, currency: "USD", trialDays: 7,
          stripePriceEnv: "STRIPE_PRICE_ID_PRO_YEARLY",
        },
      ],
      entitlements: {
        features: createBillingFeatureFlags({
          billingPortal: true, multiModelAccess: true, webSearch: true,
        }),
        limits: { maxMembers: null, monthlyAiResponses: null },
      },
    },
  },
});

Dropping the free tier (paid-only)

Two shapes:

// (a) Locked floor: orgs can sign in, but everything stays gated until they subscribe.
defineBillingCatalog({
  baseline: {
    name: "Inactive",
    description: "Subscribe to unlock the product.",
    visibleAsPlan: false, // no "Free" card on the pricing grid
    entitlements: {
      features: createBillingFeatureFlags(),
      limits: { maxMembers: 1, monthlyAiResponses: 0 },
    },
  },
  plans: { pro: { /* ... */ } },
});

// (b) Hard paywall: omit `baseline`. Unsubscribed orgs land in `paywalled`
// and the dashboard sends them to billing until they subscribe.
defineBillingCatalog({
  plans: { pro: { /* ... */ } },
});

For trial-only, omit (or lock) the baseline and set trialDays on every paid plan. New orgs must start a trial via checkout.

What ships today

Knobs in the kit

Change the catalog file, restart, and marketing, dashboard, checkout, and entitlement checks all update.

Paths above are under billingCatalogDeclaration.

Knobs in the Stripe Dashboard

No code changes. These live in your Stripe account.

Recipes

Subscription Phases

resolveBillingState turns the persisted Subscription row into a BillingPhase. That phase answers three questions: does the org have access, is billing blocked, and what should the UI show?

Baseline floor means: the declared baseline if present, otherwise the synthetic locked floor (everything off, limits 0).

Remember two rules:

• grace_period keeps paid access. The first failed charge does not downgrade; Stripe drives recovery and the kit reflects it.
• configuration_error is the only blocking phase. Every other phase decides free vs paid and lets the request through.

Checkout And Portal

Two procedures cover the billing page. Both require withPermission(billing: ["manage"]): members can read state; only admins start checkout or open the portal.

billing.createCheckout

1. Client sends { planSlug, interval } (never a Stripe price ID).
2. assertBillingEnabled() throws BAD_REQUEST if billing is not configured.
3. getCurrentOrganizationBilling(headers) resolves the active org and BillingState.
4. getCheckoutConflict(billing) checks eligibility from phase (not raw Stripe status).
5. Reject with CONFLICT when the result is configuration_error, active (already subscribed; use the portal), or recover (fix the existing subscription first). null means proceed.
6. resolveForward({ planSlug, interval }) maps to the server-only price ID and trial (BAD_REQUEST on unknown plan/interval).
7. getOrCreateCustomer(orgId) ensures Organization.stripeCustomerId.
8. createCheckoutSession(...) returns the hosted Checkout URL.

The dashboard does window.location.assign(url). Success returns to getCheckoutSuccessUrl() (?success=true); cancel returns to getCheckoutCancelUrl() (?canceled=true). The page reads those params for toasts.

billing.createPortal

1. assertBillingEnabled().
2. canOpenBillingPortal(billing) is true only when phase is entitled or grace_period and the plan has billingPortal: true.
3. createPortalSession({ customerId, returnUrl }) returns the hosted portal URL.

The portal covers plan changes, payment method, invoices, and cancel. The kit also exposes in-app cancel/resume (billing.cancel, billing.resume) that toggle cancel_at_period_end without leaving the dashboard.

The dashboard billing page

/dashboard/billing has four blocks:

Marketing pricing (PricingSection) reads the same catalog but shows monthly amounts and sends CTAs to signup. Checkout needs an active org.

Payment Methods And Tax

Payment methods are Dashboard-driven

createCheckoutSession does not set payment_method_types. Stripe uses Settings → Payment methods and renders what you enable. Cards are on by default; toggle Apple Pay, Google Pay, Link, Cash App, SEPA, iDEAL, Bancontact, and others without redeploying. Pinning payment_method_types: ["card"] in code suppresses wallets, so the kit leaves the list unset.

Tax is opt-in via one env var

Stripe Tax covers VAT, GST, and US sales tax. It is off by default: enabling it without a Stripe Tax registration makes Checkout fail. Two steps:

When the flag is unset, Checkout may still collect an address (billing_address_collection: "auto") but does not enforce one or run tax. If billing is off (isBillingEnabled is false), none of this applies.

The Webhook Path

Deep dive: Webhooks And Async Workflows: The Stripe Webhook. Below is the billing dispatch table.

Idempotency has two layers:

1. StripeWebhookEvent.eventId is claimed before any handler runs. Re-deliveries are no-ops.
2. Each email/analytics dispatch claims (kind, key) in OutboundEffect, so the same business action cannot fire twice.

See the linked Webhooks page for failure modes.

Entitlements And Gating

Read the state

Inside an oRPC procedure:

import { getCurrentOrganizationBilling } from "@/lib/billing";

const { organization, billing } = await getCurrentOrganizationBilling(headers);

Outside a procedure (scripts, non-procedure server actions), call getBillingState(orgId) from @syntaxkit/payments/server.

Gate a feature

import { assertBillingFeature } from "@/lib/billing";

assertBillingFeature(
  billing,
  "webSearch",
  "Upgrade to Pro to enable web search."
);

Throws CONFLICT on a blocking billing issue (catalog mismatch) and FORBIDDEN when the feature is off the plan. The optional third argument is the upgrade copy shown to the user.

Gate a limit

For caps on side-effecting work (AI response, billable API call), use a reservation. It counts the active window and inserts the usage row in one advisory-locked prisma.$transaction, so two concurrent callers cannot both pass a stale under-cap check.

import { reserveAiUsageEvent } from "@/lib/billing";

const usage = await reserveAiUsageEvent(billing, organization.id, {
  kind: "chat_send",
  chatId: null,
  createdByUserId: user.id,
});

try {
  // ... call the model / do the billable work ...
} catch (error) {
  // Best-effort refund: free the monthly slot for the next request.
  await prisma.aiUsageEvent
    .delete({ where: { id: usage.id } })
    .catch(() => {});
  throw error;
}

For checks that do not need atomicity (Upgrade banner, member-invite form), use the assert helpers:

import { assertWithinAiResponseLimit, assertWithinMemberLimit } from "@/lib/billing";

await assertWithinAiResponseLimit(billing, organization.id);
await assertWithinMemberLimit(billing, organization.id);

All three throw CONFLICT on a blocking issue or when the cap is reached. Add your own helpers with the same shape.

Surface upsells

The thrown FORBIDDEN message is the upgrade copy. On the client, toast it from useChat's onError (or any error boundary):

const { sendMessage } = useChat({
  onError: (error) => toast.error(error.message),
  // ...
});

That surfaces "Upgrade to Pro to enable web search." with no extra wiring.

Customizing The Catalog

Worked example: add a Team tier between Free and Pro.

STRIPE_PRICE_ID_TEAM_MONTHLY="price_..."
STRIPE_PRICE_ID_TEAM_YEARLY="price_..."

team: {
  name: "Team",
  description: "For growing teams",
  recommended: true,
  prices: [
    { interval: "month", amount: 99, currency: "USD", trialDays: 7, stripePriceEnv: "STRIPE_PRICE_ID_TEAM_MONTHLY" },
    { interval: "year",  amount: 990, currency: "USD", trialDays: 7, stripePriceEnv: "STRIPE_PRICE_ID_TEAM_YEARLY" },
  ],
  entitlements: {
    features: createBillingFeatureFlags({ billingPortal: true, webSearch: true }),
    limits: { maxMembers: 10, monthlyAiResponses: 1000 },
  },
},

Stripe owns money. The catalog owns plans. Entitlement helpers own access. Add the tier in those three places; the rest follows.

Where To Go Next

Also useful: Organizations, API, and Setup: Billing (Stripe).