Billing

SyntaxKit ships a complete B2B subscription billing layer on top of Stripe, the most trusted payments platform for SaaS. Subscriptions are scoped to organizations, not users, so a Pro plan is a team-level entitlement. Checkout uses Stripe-hosted pages so card details never touch your domain. Every knob (tiers, intervals, trial length, feature flags, limits) lives in one config file and is yours to tune. Polar and LemonSqueezy adapters are on the roadmap; the kit's BillingState and entitlements layer is already provider-agnostic.

How A Subscription Comes To Life

The flow has two halves. The synchronous half (top of the diagram) creates a Stripe-hosted Checkout session and sends the user there; on success the dashboard simply navigates back with a query param so the page can show a toast. The asynchronous half (dotted edges) is Stripe's webhook telling the kit what actually happened. processWebhookEvent claims the event id (so retries don't double-process), upserts the Subscription row, calls syncCurrentOrganizationSubscription to update Organization.currentSubscriptionId, and dispatches transactional email and analytics through OutboundEffect so each side effect runs at most once. The next request that calls getBillingState reads the new row and resolves to the entitled phase.

The diagram source lives at apps/docs/diagrams/billing-checkout-flow.mmd. Rerun pnpm --filter @syntaxkit/docs diagrams:build after editing it to refresh both SVG variants.

Package Layout

What's Wired In

Why These Choices

Stripe-only at launch

Battle-tested, B2B-native, every operator already knows it. Polar and LemonSqueezy adapters are planned next; the kit's BillingState and entitlements layer is already provider-agnostic, so adding a provider is swapping the Stripe wrapper, not rewriting consumers.

Hosted checkout over a custom page

Stripe absorbs PCI scope, 3DS / SCA, Apple Pay, Link, Cash App, and tax collection. Customers trust the Stripe domain. There is no card form to maintain, audit, or break.

Custom thin layer over the Better Auth Stripe plugin

The Better Auth Stripe plugin is in beta and user-scoped. Billing here is product-critical and org-scoped. A small in-repo wrapper means zero version-lock risk and exactly the entitlements model the kit needs.

Server-only price IDs

Stripe price IDs live in server-only STRIPE_PRICE_ID_* env vars and never reach the client bundle. The browser sends a plan slug + interval to checkout; the server resolves the price ID from the catalog. The marketing page and dashboard render display amounts (no price IDs) from the catalog.

Pricing Plans And Catalog

The catalog is one TypeScript object you declare with defineBillingCatalog in packages/payments/src/catalog/declaration.ts. It has two parts (see ADR 0002): an optional baseline (what an organization with no active subscription gets) and the plans map of purchasable tiers. Each price names a server-only env var (stripePriceEnv) that holds its Stripe price ID. The ID itself is never written in the file or shipped to the client. Everything below is a default; the next section is a tour of the knobs you can tune.

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)

The baseline is what makes "no free tier" possible. Two paid-only shapes:

// (a) Paid-only with a usable-but-locked floor: unsubscribed orgs can sign in
// but everything is 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 the `paywalled`
// phase and the dashboard routes them to the billing page until they subscribe.
defineBillingCatalog({
  plans: { pro: { /* ... */ } },
});

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

What ships today

Configurability: What You Can Tune

Every value below is a default. Change the file, restart the app, and the catalog updates everywhere: marketing pricing page, dashboard plan grid, checkout, and entitlement checks.

Knobs in the kit

Knobs in the Stripe Dashboard

These do not require code changes. They live in your Stripe account.

Three concrete recipes

Subscription Phases

A subscription's effective state is a BillingPhase, derived from the persisted Subscription row by resolveBillingState. The phases and the transitions between them:

The "baseline floor" is the declared baseline when one exists, or the synthetic locked floor (everything off, limits 0) on a hard-paywall catalog.

Two callouts worth burning into memory:

• grace_period keeps paid access. The kit does not abruptly downgrade on the first failed charge; Stripe drives recovery, the kit reflects it.
• configuration_error is the only blocking phase. Every other phase makes its decision (free vs paid) cleanly and lets requests through.

Connecting Stripe

The first-time Stripe walkthrough (account, products, env vars, webhook endpoint, Stripe CLI for local dev) lives on Setup: Billing (Stripe). When pnpm setup:doctor reports Stripe billing: OK, head back here for the deeper coverage of how the subscription lifecycle, entitlements, and dashboard UI fit together.

For the test-to-live cutover (live keys, live price ids, live webhook endpoint), see Going To Production: Pricing And Stripe Live Mode.

Local Development With The Stripe CLI

The asynchronous half of billing — the part that actually creates the Subscription row — only fires when Stripe can reach your webhook endpoint. On a deployed app that's a public URL; on localhost it isn't, so Stripe can't call you. The Stripe CLI closes the gap: stripe listen opens a tunnel from your Stripe test account to localhost:3000/api/webhooks/stripe and prints a signing secret for the session, so the whole loop — checkout, webhook, entitlement flip — runs end-to-end on your machine with test-mode keys and test cards. No money moves; nothing reaches a real card network.

This is the canonical local-billing walkthrough. The Setup: Billing (Stripe) page gets you the account, products, and env vars; come back here once pnpm setup:doctor reports Stripe billing: OK.

One-time CLI setup

stripe login

The end-to-end loop

Run the app and the CLI side by side, then drive a real checkout. You need two terminals.

pnpm dev

stripe listen --forward-to localhost:3000/api/webhooks/stripe

STRIPE_WEBHOOK_SECRET="whsec_..."

Simulating events with stripe trigger

Clicking through Checkout exercises the happy path, but the kit handles a dozen events (see The Webhook Path) — trials ending, payments failing, subscriptions canceling. You don't need to reproduce each one by hand. With stripe listen running in Terminal 2, fire any event from a third terminal:

# Re-run the checkout-completed handler
stripe trigger checkout.session.completed

# Drive the subscription lifecycle handlers
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted
stripe trigger customer.subscription.trial_will_end

# Exercise the dunning / invoice emails
stripe trigger invoice.payment_failed
stripe trigger invoice.payment_succeeded

Each trigger creates the underlying test objects in Stripe and forwards the resulting event through your listener, so you can watch a handler run — and the email/analytics side effect dispatch — without a real subscription in that state. Use it to test the lifecycle emails (log mode writes them to .local/email-outbox/*.eml) or to confirm a new handler you've wired up actually fires.

Test cards

Stripe test mode accepts a small set of magic card numbers. The two you'll reach for most:

For every card, use any future expiry, any 3-digit CVC, and any postal code. Stripe's test-cards reference is the source of truth and lists many more (3DS / SCA challenges, specific decline codes, regional methods) — reach for it when you need a scenario beyond success and decline.

Keeping the catalog honest

pnpm billing:check-prices compares each paid price you declare in billingCatalogDeclaration against its live Stripe Price and fails on amount/currency drift, archived, or missing Prices. Run it after you create or re-point a test-mode Price (or change a declared amount/currency) to confirm the catalog and Stripe still agree before you click Upgrade — a mismatch is what produces the configuration_error phase. It's a test/script-only guard and never runs on a request; see the catalog callout above for the full drift story.

Payment Methods And Tax

Two production concerns deserve a one-paragraph mental model before launch: which payment methods appear at checkout, and whether sales tax / VAT is collected on top of the price.

Payment methods are Dashboard-driven

createCheckoutSession does not set payment_method_types. Stripe takes the list from your Dashboard at Settings -> Payment methods and renders only what you've enabled. Cards are on by default; you can toggle Apple Pay, Google Pay, Link, Cash App, SEPA Direct Debit, iDEAL, Bancontact, and the rest without redeploying. Pinning the list in code (the older payment_method_types: ["card"] pattern) actively suppresses everything else, including wallets, so the kit deliberately leaves it off.

Tax is opt-in via one env var

Stripe Tax is the production answer to VAT (EU/UK), GST (AU/NZ/CA), and US sales tax. It's off by default in the kit because turning it on without a Stripe Tax registration causes Checkout to fail. Two steps to enable it:

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

Checkout And Portal

Two procedures cover everything users do on the billing page. Both are gated by withPermission(billing: ["manage"]) so non-admin members can read state but not start checkout or open the portal.

billing.createCheckout

Phases of the handler:

1. The client sends { planSlug, interval }, never a Stripe price ID.
2. assertBillingEnabled() throws BAD_REQUEST if billing is not configured in this environment.
3. getCurrentOrganizationBilling(headers) resolves the active org and BillingState.
4. Classify eligibility with getCheckoutConflict(billing): one derived check on the resolved phase (no raw status matching).
5. Reject with CONFLICT when it returns configuration_error (catalog mismatch), active (already subscribed, use the portal), or recover (a non-terminal subscription must be recovered first); null lets checkout proceed.
6. resolveForward({ planSlug, interval }) resolves the server-only Stripe price ID and trial from the catalog (BAD_REQUEST on an unknown plan/interval).
7. getOrCreateCustomer(orgId) ensures Organization.stripeCustomerId is set.
8. createCheckoutSession({ priceId, customerId, trialDays, successUrl, cancelUrl }) returns a Stripe-hosted URL.

The dashboard does window.location.assign(url). After payment, Stripe redirects back to getCheckoutSuccessUrl() (which appends ?success=true); on cancel, getCheckoutCancelUrl() appends ?canceled=true. The dashboard reads those query params to show toasts.

billing.createPortal

1. assertBillingEnabled().
2. canOpenBillingPortal(billing) returns true whenever the org has a stored Stripe customer and the phase can reach the portal: entitled / grace_period (with the plan's billingPortal: true), plus recoverable and configuration_error — so a customer whose payment failed or whose plan fell out of the catalog can always get back to Stripe to pay or fix their subscription. Only free / paywalled / lapsed and customers with no stored Stripe customer are denied.
3. createPortalSession({ customerId, returnUrl }) returns a Stripe-hosted URL.

The portal is the universal "manage billing" surface: change plan, change payment method, view invoices, cancel. The kit also offers in-app cancel + resume (billing.cancel, billing.resume) that toggle cancel_at_period_end directly through the API for users who don't want to leave the dashboard.

Trial Abuse Boundary

Trials are first-subscription-only, per organization. createCheckoutSession (packages/payments/src/stripe/checkout.ts) only attaches trial_period_days when the organization has no prior Subscription row — it counts prisma.subscription.count({ where: { organizationId } }) and skips the trial when that is non-zero. Any historical row disqualifies the org regardless of status (canceled, expired, or otherwise), so the classic "cancel and re-checkout for another free trial" loop is dead: an org gets exactly one trial, ever.

That guard is org-scoped, and organizations are free to create. A determined user can therefore still farm unlimited trials by spinning up a fresh organization per trial — each new org has no subscription history, so each qualifies for its own trial. This is inherent to org-scoped billing (the same team-level model that makes a Pro plan an organization entitlement rather than a user one), not a gap in the checkout guard.

Two mitigations fit the kit without abandoning the org-scoped model:

The Webhook Path (Billing-Specific)

The webhook deep dive lives at Webhooks And Async Workflows: The Stripe Webhook. What follows is the billing-specific dispatch table: each row is one Stripe event the kit handles.

The two-layer idempotency story: StripeWebhookEvent.eventId is claimed atomically before any handler runs (Stripe re-deliveries are no-ops); each email and analytics dispatch claims its own (kind, key) row in OutboundEffect so the same business action can never fire twice. See the linked Webhooks page for the failure-mode walkthrough.

Entitlements And Gating

How to actually use this from your code.

Read the state

Inside an oRPC procedure, use the helper:

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

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

Outside an oRPC procedure (e.g. a one-off script, a non-procedure server action), call getBillingState(orgId) from @syntaxkit/payments/server directly.

Gate a feature

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

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

assertBillingFeature throws CONFLICT when there's a blocking billing issue (catalog mismatch) and FORBIDDEN when the feature isn't on the plan. The optional third argument is the upgrade copy that flows back to the user.

Gate a limit

For caps that gate a side-effecting action (an AI response, a billable API call), use a reservation: it counts the active window AND inserts the usage row inside one advisory-locked prisma.$transaction, so concurrent callers can't both pass a stale "under cap" check and then both write usage rows.

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: the monthly slot is freed for the next request.
  await prisma.aiUsageEvent
    .delete({ where: { id: usage.id } })
    .catch(() => {});
  throw error;
}

For predicate-style checks that don't need atomicity (rendering an "Upgrade" banner, gating a member invitation form), keep using 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 with the same shape.

Surface upsells

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

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

That gives you "Upgrade to Pro to enable web search." in the UI without any extra wiring.

The Dashboard Billing Page

/dashboard/billing has four UI blocks:

Marketing pricing (PricingSection on the homepage) renders the same billingCatalogDeclaration but only shows monthly amounts and CTAs go to signup, not checkout. Checkout requires an active org.

Customizing The Catalog (Worked Example: Adding A Team Tier)

The previous section listed every knob. This one walks through the most-asked extension end-to-end: a new "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 },
  },
},

That's the entire change. Stripe holds the truth about money; the catalog file holds the truth about plans; entitlement helpers hold the truth about access. Add a tier in three of those layers and the rest follows.

Where To Go Next