Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/convex/agent-skills --skill convex-billingAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
<!-- 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:
ts
import { defineApp } from 'convex/server';
import stripe from '@convex-dev/stripe/convex.config.js';
const app = defineApp();
app.use(stripe);
export default app;- Store Stripe keys in Convex env (use the
envmicro power):STRIPE_SECRET_KEY(sktest… / sklive…) andSTRIPE_WEBHOOK_SECRET(whsec_…). - Create
convex/http.tsto register the webhook route (the component handles signature verification automatically):
ts
import { httpRouter } from 'convex/server';
import { components } from './_generated/api';
import { registerRoutes } from '@convex-dev/stripe';
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:
ts
import { action, query } from './_generated/server';
import { components } from './_generated/api';
import { StripeSubscriptions } from '@convex-dev/stripe';
import { v } from 'convex/values';
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): STRIPESECRETKEY and STRIPEWEBHOOKSECRET. - 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.
