convex-billing
Add Stripe billing/payments to the Convex app via @convex-dev/stripe (checkout + webhook + gating).
- License 许可
- MIT
- 所属仓库
- openclaw/clawhub
- 最近更新
- 2026-11-15
- Stars
- ★ 9.6k
- Forks
- 1.5k
01 前言 Front Matter
- name
- convex-billing
- description
- Add Stripe billing/payments to the Convex app via @convex-dev/stripe (checkout + webhook + gating).
03 SKILL.md 正文
<!-- GENERATED from convex-agents content/capabilities/billing.json — do not edit by hand. -->
Add billing / payments
Wire Stripe to Convex using @convex-dev/stripe: a checkout action, an httpAction webhook registered by the component (signature-verified automatically), subscription state stored in the component's tables, and server-side gating via a query.
Workflow
- Install the component:
npm install @convex-dev/stripe. - Create
convex/convex.config.ts:import stripe from "@convex-dev/stripe/convex.config.js"; import { defineApp } from "convex/server"; const app = defineApp(); app.use(stripe); export default app; - Store Stripe keys in Convex env (use the
envmicro power):STRIPE_SECRET_KEY(sk_test_… / sk_live_…) andSTRIPE_WEBHOOK_SECRET(whsec_…). - Create
convex/http.tsto register the webhook route (the component handles signature verification automatically):import { registerRoutes } from "@convex-dev/stripe"; import { httpRouter } from "convex/server"; import { components } from "./_generated/api"; const http = httpRouter(); registerRoutes(http, components.stripe, { webhookPath: "/stripe/webhook" }); export default http; - Create
convex/billing.tswith a checkout action and a subscription-gate query:import { StripeSubscriptions } from "@convex-dev/stripe"; import { v } from "convex/values"; import { components } from "./_generated/api"; import { action, query } from "./_generated/server"; const stripeClient = new StripeSubscriptions(components.stripe, {}); export const createSubscriptionCheckout = action({ args: { priceId: v.string() }, returns: v.object({ sessionId: v.string(), url: v.union(v.string(), v.null()) }), handler: async (ctx, args) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) throw new Error("Not authenticated"); const customer = await stripeClient.getOrCreateCustomer(ctx, { userId: identity.subject, email: identity.email, name: identity.name, }); return await stripeClient.createCheckoutSession(ctx, { priceId: args.priceId, customerId: customer.customerId, mode: "subscription", successUrl: `${process.env.SITE_URL ?? "http://localhost:3000"}/?success=true`, cancelUrl: `${process.env.SITE_URL ?? "http://localhost:3000"}/?canceled=true`, subscriptionMetadata: { userId: identity.subject }, }); }, }); export const isSubscribed = query({ args: {}, returns: v.boolean(), handler: async (ctx) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) return false; const subscriptions = await ctx.runQuery( components.stripe.public.listSubscriptionsByUserId, { userId: identity.subject }, ); return subscriptions.some((sub) => sub.status === "active" || sub.status === "trialing"); }, }); - Run
npx convex dev --once— it will install the component and push the functions. Verify output shows✔ Installed component stripe. - In Stripe Dashboard → Webhooks: add endpoint
https://<deployment>.convex.site/stripe/webhook, subscribe tocheckout.session.completed,customer.subscription.*,invoice.*,payment_intent.*. Copy the signing secret asSTRIPE_WEBHOOK_SECRET.
Rules
- Use @convex-dev/stripe (npm: @convex-dev/stripe@^0.1.4) — it handles webhook signature verification internally via registerRoutes; do NOT write a manual constructEvent webhook.
- Stripe keys live in Convex env (use the
envmicro power): STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET. - Gate on server-stored subscription state via isSubscribed query (reads component tables), not client claims.
- convex/convex.config.ts must import from '@convex-dev/stripe/convex.config.js' (not .ts) — the .js extension is required by the Convex bundler.
04 同仓库更多 Skills
notes
Turn user-provided notes into a concise agenda.
hosted-research
Read approved reference material for the hosted proof.
convex-advisor
Read the Convex deployment's 72h insights (read limits, OCC contention), root-cause each event in code, report evidence-backed perf/cost findings with fixes.
convex-add
Add a capability to the CURRENT Convex app — consults the served Convex capability catalog for always-current procedures (billing, crons, auth, agent, search, …); falls back to built-in hosting or @convex-dev component search. TRIGGER when the user runs /add, or asks to add hosting/publishing or any backend capability to an existing Convex app.
convex-acquire-domain
Find and buy a domain for the current Convex app through Convex, then bind it (labs; spend action).
controlling-costs
Analyzes Axiom query patterns to find unused data, then builds dashboards and monitors for cost optimization. Use when asked to reduce Axiom costs, find unused columns or field values, identify data waste, or track ingest spend.