Skip to content
Get packs

Guide · Agent skill

How to use the Add Stripe billing to Convex agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The convex-billing skill is a step-by-step recipe that teaches an AI agent to add Stripe subscriptions to an app built on Convex, a backend platform. Once installed, the agent can wire up the @convex-dev/stripe component, a checkout action, a webhook and a server-side check of whether a user has paid. This guide explains what the skill does, how to install it, how to ask for it, and what to check before you ship.

Add Stripe billing to Convexopenclaw/clawhub · MIT

Quick start

  1. 1Download and install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Prepare your Convex project. Make sure Node.js, npm and a Convex project are in place, and that you have a Stripe account with test keys.
  3. 3Ask the agent for subscription billing. Describe the goal in plain language, such as adding Stripe subscriptions and gating features for paying users.
  4. 4Store Stripe keys in Convex. Save STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as Convex environment variables using the env micro power.
  5. 5Run convex dev once. Run npx convex dev --once so the component installs and the functions are pushed. Confirm the output shows Installed component stripe.
  6. 6Register the Stripe webhook. In the Stripe Dashboard, add the endpoint https://<deployment>.convex.site/stripe/webhook, subscribe to the listed events, and copy the signing secret into Convex.
  7. 7Test before going live. Use test keys to run a checkout and confirm the isSubscribed query returns true before switching to live keys.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when it is relevant to your request. This skill is named convex-billing and its description is: Add Stripe billing/payments to the Convex app via @convex-dev/stripe (checkout + webhook + gating).

When the skill is active, the agent follows its workflow to set up paid subscriptions. It installs the component, creates convex/convex.config.ts, registers a webhook route in convex/http.ts, and creates convex/billing.ts with a checkout action and an isSubscribed query. The skill also tells the agent to store Stripe keys in Convex environment variables and not to write its own webhook signature code.

  • Creates a checkout action that starts a Stripe subscription purchase (mode: subscription).
  • Registers a webhook so Stripe can report payment events; the component verifies signatures automatically.
  • Adds a query that returns true only if the signed-in user has an active or trialing subscription.
  • Keeps STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in Convex environment variables.

How do you install the convex-billing skill?

The skill ships as a ZIP download from this page. Choose one of the two options below depending on how you use your agent.

For Claude Code, unzip the downloaded file into ~/.claude/skills/ to make it available in all your projects, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need before you start?

The skill assumes an existing Convex project and does not create one. You also need a Stripe account with test and/or live API keys. The recipe uses the npm package @convex-dev/stripe at version ^0.1.4 and the 'env' micro power for Convex environment variables.

The skill's code expects the Convex component and generated API files, so it is written for Convex projects specifically.

  • Node.js and npm
  • A Convex project
  • A Stripe account with API keys (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET)
  • npm package @convex-dev/stripe (^0.1.4)
  • Convex environment variable support via the 'env' micro power

How do you trigger the skill with a natural request?

You do not need special syntax. Describe the outcome you want in plain language inside a Convex project, and mention Stripe and subscriptions. The agent should recognise that the request matches the skill's description.

Good requests name the goal, the platform and the access rule. For example, you can ask the agent to add paid subscriptions with Stripe to your Convex app, or to make certain features available only to users with an active subscription.

  • Add Stripe subscriptions to my Convex app with a checkout button.
  • Set up a Stripe webhook in Convex and gate the dashboard for paying users.
  • Check on the server whether the current user has an active subscription in Convex.

What does the setup look like in code?

The core of the skill is a short set of files. The convex.config.ts file registers the Stripe component, and the import must use the .js extension, which the skill notes is required by the Convex bundler.

The billing file creates a checkout action that gets or creates a Stripe customer for the signed-in user and then starts a subscription checkout session. The isSubscribed query reads subscription state stored in the component's tables, so access is decided on the server rather than from client claims.

  • convex/convex.config.ts: imports the stripe component and calls app.use(stripe).
  • convex/http.ts: registers the webhook at /stripe/webhook.
  • convex/billing.ts: defines createSubscriptionCheckout and isSubscribed.
npm install @convex-dev/stripe npx convex dev --once

How do you finish the Stripe webhook setup?

After the code is pushed, the skill directs you to Stripe Dashboard → Webhooks. Add an endpoint at https://<deployment>.convex.site/stripe/webhook, replacing <deployment> with your own deployment name. Subscribe to checkout.session.completed, customer.subscription.*, invoice.* and payment_intent.*. Then copy the signing secret into Convex as STRIPE_WEBHOOK_SECRET.

The skill says to confirm that the output of npx convex dev --once shows the line Installed component stripe.

  • Endpoint: https://<deployment>.convex.site/stripe/webhook
  • Events: checkout.session.completed, customer.subscription.*, invoice.*, payment_intent.*
  • Store the signing secret as STRIPE_WEBHOOK_SECRET

What people use it for

  • Adding a monthly or yearly paid plan to a SaaS app built on Convex.
  • Restricting premium pages or features to users with an active or trialing subscription.
  • Creating a Stripe customer record linked to each signed-in user on first checkout.
  • Setting up a known-good Stripe webhook route in Convex instead of writing signature code by hand.

Frequently asked questions

Is the convex-billing skill free?

The skill is released under the MIT licence, as listed on this page. Stripe itself charges its own fees for payment processing, which are separate from the skill.

What do I need to use the convex-billing skill?

You need Node.js and npm, an existing Convex project, a Stripe account with test and/or live API keys, the @convex-dev/stripe npm package at ^0.1.4, and Convex environment variable support through the env micro power.

Does the skill work with apps that are not built on Convex?

No. The code assumes the Convex component and generated API files, so the skill will not work as written in other backends.

Does this skill handle one-off payments or PayPal?

No. The recipe covers only Stripe subscriptions. It does not cover one-off payments or non-Stripe payment processors.

Does the skill run scripts on my machine?

The skill does not run scripts, according to its listing. It does use the network, because the setup connects your Convex app to Stripe and Stripe sends webhook events to your deployment.

Why does the agent not write its own webhook signature check?

The skill tells the agent to use @convex-dev/stripe, which verifies webhook signatures automatically through registerRoutes. Writing a custom constructEvent handler is explicitly discouraged in the skill.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building a SaaS app on Convex and want a tested-looking starting point for Stripe subscriptions, server-side access checks and webhook setup. Pick something else if your app is not on Convex, you need one-off payments or another processor, or you cannot test thoroughly, since misconfigured billing or webhook logic can cause real charges or access errors.

Download the skill