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.

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 only when phase is entitled or grace_period and the plan has billingPortal: true.
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.

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