Payments (Stripe)

The Payments add-on registers the official @convex-dev/stripe Convex component. The component owns the customers/subscriptions/payments/invoices tables, syncs them from Stripe webhooks, and gives you typed queries you can read from the glasses app and the companion site alike.

You write almost no Stripe code. You enable the add-on, wire keys

• prices + a webhook URL. The rest is already there.

Enable

The shipped CLI is the recommended path. One command renames all the .disabled files back to active and inserts the relevant content into the fenced regions of shared files. You then push your Stripe keys to the Convex dashboard separately.

pnpm run addon enable payments

To roll back later: pnpm run addon disable payments.

What the CLI does

When pnpm run addon enable payments runs, it:

• Renames .ts.disabled / .tsx.disabled files for:
  • packages/backend/convex/stripe.ts
  • packages/backend/convex/entitlements.ts
  • packages/backend/convex/lib/priceToPlan.ts + .test.ts
  • companion/components/checkout-button.tsx
  • companion/components/landing/pricing-section.tsx
  • companion/components/dashboard-billing-section.tsx
• Renames companion/app/_pricing/ → companion/app/pricing/ so Next.js routes it; renames its page.tsx.disabled → page.tsx
• Inserts the Stripe imports + app.use(stripe) in convex.config.ts
• Inserts the Stripe webhook route in http.ts
• Inserts the STRIPE_* schema in env.ts (Convex) + NEXT_PUBLIC_STRIPE_PRICE_* in companion/env.ts
• Inserts the <PricingSection /> import + JSX in landing
• Inserts the "Pricing" entries in nav + footer columns of companion/lib/config.ts
• Inserts the example pricing config block (Pro + Team tiers)
• Inserts the <DashboardBillingSection /> import + JSX in the dashboard

Selling one-time products instead of subscriptions

The CheckoutButton already accepts mode: "subscription" | "payment". To convert the default subscription example to one-time payments:

const payments = await ctx.runQuery(
  components.stripe.lib.listPaymentsByUserId,
  { userId },
);
const paid = payments.find((p) => p.status === "succeeded");
if (paid) return planFromPriceId(paid.priceId);
return "free";

export type Plan = "free" | "pro" | "team" | "lifetime";

<CheckoutButton priceId={tier.priceId} mode="payment">
  {tier.cta}
</CheckoutButton>

What ships in the box

Wiring it up

STRIPE_SECRET_KEY=sk_test_...

# Map your real price IDs to plan names (used by entitlements.ts).
STRIPE_PRICE_PRO=price_...
STRIPE_PRICE_TEAM=price_...

NEXT_PUBLIC_STRIPE_PRICE_PRO=price_...
NEXT_PUBLIC_STRIPE_PRICE_TEAM=price_...

STRIPE_WEBHOOK_SECRET=whsec_...

How entitlement works

There is no plan column on users. entitlements.getMyPlan reads the Stripe component's synced subscriptions and maps the active subscription's priceId → STRIPE_PRICE_PRO → "pro". Convex queries are reactive, so the moment a webhook updates a subscription, every client's plan updates.

Unknown / unset price IDs fall back to "free". The mapping lives in packages/backend/convex/entitlements.ts. Edit PRICE_TO_PLAN there if you add tiers.

Customer portal

stripe.createPortalSession redirects the user to Stripe's hosted portal where they can update card, cancel, or download invoices. Enable the portal in Stripe first:

The dashboard's Manage billing button calls api.stripe.createPortalSession and redirects.

One-time payments

createCheckout already takes mode: "subscription" | "payment". For one-time charges, pass "payment":

<CheckoutButton priceId={priceId} mode="payment">
  Buy lifetime access
</CheckoutButton>

The component will create a payment_intent instead of a recurring subscription; the synced data shows up in getMyAccount().payments.

Selling YOUR product (not just the example tiers)

The Stripe wiring above is the boilerplate's example checkout: Pro and Team tiers shipped as a working reference. To sell your own product to your glasses users, you reuse the same component, add your own price IDs, and extend entitlements.ts.

const PRICE_TO_PLAN: Record<string, Plan> = {
  [process.env.STRIPE_PRICE_PRO ?? ""]: "pro",
  [process.env.STRIPE_PRICE_TEAM ?? ""]: "team",
};

const PRICE_TO_PLAN: Record<string, Plan> = {
  [process.env.STRIPE_PRICE_SOLO ?? ""]: "solo",
  [process.env.STRIPE_PRICE_PRO ?? ""]: "pro",
  [process.env.STRIPE_PRICE_PRO_ANNUAL ?? ""]: "pro",
  [process.env.STRIPE_PRICE_LIFETIME ?? ""]: "pro",
};

export type Plan = "free" | "solo" | "pro";

import { useQuery } from "convex/react";
import { api } from "@glasskit/backend/convex/_generated/api";

function CoolFeature() {
  const { plan } = useQuery(api.entitlements.getMyPlan) ?? { plan: "free" };
  if (plan === "free") return <UpgradeNudge />;
  return <TheActualFeature />;
}

Going live

Troubleshooting