Hype StackHypeStack

Billing (Stripe)

Stripe integration, subscriptions, and billing flows. This is the pack-billing-stripe pack, the default of the three billing variants. The other two, Lemon Squeezy and Polar, are merchants of record and ship the same product shape.

What you need

  • A Stripe account. Sign up at dashboard.stripe.com.
  • Postgres and Valkey (subscription status is cached in Valkey, keyed by organization).
  • Optionally Resend for receipt emails. If RESEND_API_KEY is set, the pack sends receipts; otherwise it skips email.

Stripe credentials

From the Stripe dashboard, grab:

  • Secret key (STRIPE_SECRET_KEY) and publishable key (STRIPE_PUBLISHABLE_KEY) from API Keys.
  • Webhook signing secret (STRIPE_WEBHOOK_SECRET) from Webhooks, or create one locally with the Stripe CLI (below).
  • Price IDs for the plans you sell (STRIPE_PRICE_PRO, STRIPE_PRICE_PREMIER in the pack's env schema).

Data model

There is no Prisma "subscriptions" table in this pack. Billing state is org-scoped and stored in Valkey:

Key patternMeaning
stripe:org:{organizationId}Stripe customer id for that organization
stripe:customer:{customerId}Cached subscription / billing status

Checkout, portal, and webhook sync code live under apps/backend/src/features/billing/ and apps/backend/src/libs/stripe/. Organization admins get MANAGE:BILLING through the pack's permission grants.

Checkout and portal flow

Subscribe an organization

  1. Create checkout

    The frontend calls the billing module. The backend creates a Stripe Checkout session for the org's customer (creating one if needed).

  2. Customer pays in Stripe

    Stripe hosts the checkout UI. Success returns to the pack's checkout-success route.

  3. Webhook sync

    POST /checkout/webhook verifies the signature, then syncs customer and subscription status into Valkey.

  4. Customer portal

    create-billing-portal opens Stripe's portal for plan changes and invoices against the same org customer.

Webhook endpoint

The pack exposes a Stripe webhook receiver at:

POST /checkout/webhook

In production, create a webhook endpoint in Stripe pointing at https://your-api-origin/checkout/webhook, subscribe to the events the pack handles (checkout, subscription, customer), and copy the signing secret into STRIPE_WEBHOOK_SECRET.

Local development with the Stripe CLI

Stripe cannot reach localhost over the internet, so use the Stripe CLI to forward events. Install it from stripe.com/docs/stripe-cli, then:

bash
stripe listen --forward-to localhost:3000/checkout/webhook

The CLI prints a whsec_... signing secret. Put it in STRIPE_WEBHOOK_SECRET.

Failure and retry notes

  • Signature verification failures reject the webhook. Fix the secret before debugging business logic.
  • Sync helpers update the Valkey cache from Stripe's customer / subscription objects. If the UI looks stale after a portal change, confirm the webhook events are arriving and the org → customer mapping exists.
  • Receipt email is best-effort: without RESEND_API_KEY the send path returns early and checkout still succeeds.

Environment variables

VariablePurpose
STRIPE_SECRET_KEYStripe API secret key
STRIPE_PUBLISHABLE_KEYPublishable key the frontend uses
STRIPE_WEBHOOK_SECRETSigning secret for the webhook endpoint
STRIPE_PRICE_PROStripe Price ID for Pro
STRIPE_PRICE_PREMIERStripe Price ID for Premier
RESEND_API_KEYOptional. Enables receipt emails

One subscription per customer

In the Stripe dashboard, under Settings > Checkout and Payment Links, turn on Limit customers to one subscription. The pack keys billing state by organization, and that setting is what stops a second checkout from creating a parallel subscription. The CLI prints this reminder after install.

Gate a feature by plan

The plan belongs to the organization, not to the person: every member of a paying org gets the paid features. There are three plans, free, pro, and premier, in features/billing/constants/plans.ts. This section is the same for all three billing packs, so code written against it keeps working if you switch providers.

On the backend

ts
import { getPlanRank } from "@backend/features/billing/constants/plans";
import { getSubscriptionStatus } from "@backend/features/billing/modules/get-subscription-status";
import { ApplicationError, ApplicationErrorCode } from "@backend/middleware/error";

const { plan } = await getSubscriptionStatus({ organizationId });

if (getPlanRank(plan) < getPlanRank("pro")) {
  throw new ApplicationError({
    code: ApplicationErrorCode.FORBIDDEN,
    message: m.invoices_error_needs_pro(),
    statusCode: 402,
  });
}

What plan tells you:

  • It is pro or premier only while the subscription is active or trialing. A past_due, unpaid, or canceled subscription reads as free.
  • A subscription cancelled at period end keeps its plan until the period ends, with cancelAtPeriodEnd: true.
  • The call reads Valkey, never Stripe, so it is cheap enough for every request. Webhooks keep the cache current. With no cached entry, for example when the webhook was never set up, every organization reads as free.

For limits that differ per plan (seats, exports per month, storage), keep one table keyed by plan and look it up:

ts
import type { PlanKey } from "@backend/features/billing/constants/plans";

const INVOICE_LIMITS = {
  free: { monthly: 10 },
  pro: { monthly: 500 },
  premier: { monthly: null },
} satisfies Record<PlanKey, { monthly: number | null }>;

const { monthly } = INVOICE_LIMITS[(await getSubscriptionStatus({ organizationId })).plan];

The AI chat pack does exactly this for its token and image allowances.

In the UI

GET /checkout/status returns the plan, but every /checkout route needs manage:billing, which only admins have. Members get a 403 from it. To show or hide a feature for everyone, return the plan from your own feature's route, which already runs as the member:

ts
.get("/access", hasAccess({ action: "read", subject: "invoice" }), async (ctx) => {
  const { plan } = await getSubscriptionStatus({ organizationId: ctx.var.organizationId });
  return ctx.json({ plan });
})

Hide or disable the feature from that response, and keep the backend check. The UI check is only there so people see an upgrade prompt instead of an error.

There is no ready-made withPlan middleware or usePlan hook yet. The snippets above are the whole pattern.

In the admin

On top of a starter, this pack adds a revenue row to the admin app dashboard, a billing card and a revenue card on the organization details page, and /admin/billing API routes. Nothing extra to configure beyond Stripe env vars; the UI shows up once both packs are installed.

Surfaces

Web, admin, and mobile. The Expo app gets the billing screen and the checkout handoff to Stripe's hosted page.