Cursor Rules for Stripe & Billing Codebases
Stripe code fails quietly: a webhook that verifies against a re-parsed body, a double-charged customer from a retried event, or a subscription that stays "active" after a card decline. The four rules below are glob-scoped to your billing paths so they load only when an agent touches Stripe code, not on every turn. Last updated 2026-10-27 by Rakshit Yadav.
Why Stripe code needs its own rule file
Billing bugs rarely throw an error. They show up as a support ticket three weeks later: a customer who paid but lost access, or one who cancelled but is still being billed. Stripe's own delivery model makes this worse for a generated codebase — webhooks can arrive more than once, out of order, or after the customer has already closed the Checkout tab. A rule file that loads only in app/api/stripe/** and lib/stripe/** catches the two or three mistakes that cause most of this before they ship, without adding always-on weight to every unrelated turn.
Rule 1: webhook signature verification
---
description: Stripe webhook signature verification
globs: app/api/webhooks/stripe/**/*.ts,app/api/stripe/webhook/**/*.ts
alwaysApply: false
---
- Read the request body with request.text() before any JSON parsing. A body that has been parsed and re-serialized will not match the signature Stripe sent.
- Pass that raw string, not a parsed object, to stripe.webhooks.constructEvent.
- Load STRIPE_WEBHOOK_SECRET per environment (test vs live) and throw at boot if it is missing, not on the first request.
- Return 400 on a bad signature. Do not fall back to trusting the payload.This is the single most common Stripe bug in agent-written code: the handler parses the body for convenience, then verification fails against the re-serialized JSON, and the fix people reach for is disabling verification instead of reading the raw body first.
Rule 2: idempotent event handling
---
description: Idempotent Stripe webhook handlers
globs: app/api/webhooks/stripe/**/*.ts,lib/stripe/**/*.ts
alwaysApply: false
---
- Insert the Stripe event id into a unique-constrained table before running any side effect. If the insert conflicts, the event was already processed; return 200 and stop.
- Never branch handler logic on headers or timing. Only the event id decides whether work has already happened.
- Return 2xx within a few seconds. Move slow work (emails, exports) to a queue after the event is recorded.Stripe retries on timeout and can send the same event twice during normal operation, not just on failure. Without this rule, a slow handler gets retried and runs its side effects twice — most visibly as a double-sent receipt or a subscription upgraded two tiers at once.
Rule 3: subscription state is Stripe's, not the redirect's
---
description: Subscription state source of truth
globs: app/api/webhooks/stripe/**/*.ts,lib/stripe/**/*.ts,app/(app)/billing/**/*.ts
alwaysApply: false
---
- Update plan, status, and current_period_end only from customer.subscription.created/updated/deleted events.
- Never grant access from the Checkout success redirect. A closed tab or slow network means the redirect never fires even though payment succeeded.
- On invoice.payment_failed, move the account to past_due; do not revoke access until the subscription itself is cancelled or past its grace period.
- Pass client_reference_id or metadata with your internal user/org id at Checkout creation so later events can be tied back without matching on email.The checkout success page is a UX detail, not a billing event. Agents told to "give the user access after checkout" will wire it to the redirect because that is the obvious place — this rule routes that instinct back to the webhook.
Rule 4: secrets and logging
---
description: Stripe secret and log hygiene
globs: app/api/stripe/**/*.ts,app/api/webhooks/**/*.ts,lib/stripe/**/*.ts
alwaysApply: false
---
- Pin the Stripe API version in one place (lib/stripe/client.ts). Do not let it float per-call.
- Never log full event payloads, card data, or customer PII. Log the event id and type only.
- The Stripe secret key is server-only. It must never be imported in a file reachable from the client bundle.These are boring until a log aggregator with broad read access becomes the actual leak. Keep them as a rule because they are a ban, not a procedure — see when a rule beats a skill.
When to graduate a rule into a skill
These four rules are bans: short, glob-scoped, and meant to fire silently. The moment you want the agent to walk through Checkout session creation, portal configuration, and a pre-launch test checklist step by step, that's a procedure, not a ban — put it in a skill instead. The Stripe billing skill covers exactly that, and the /stripe-billing command runs the full setup in one pass using these rules as guardrails.
Related pages
Frequently asked questions
Should Stripe rules be always-on?
No. Scope them with globs to your webhook and billing paths (app/api/stripe/**, lib/stripe/**). An always-on rule loads on every turn even when you're editing unrelated UI, which wastes context.What's the single most important Stripe rule?
Read the raw request body before parsing it, then verify the signature against that raw string. Verifying against a parsed-and-re-serialized body is the most common reason Stripe webhook checks fail in generated code.Do I still need these rules if I use the Stripe billing skill?
Yes. The skill teaches the full setup procedure; the rules stay loaded afterward so later edits to the webhook handler don't quietly drop idempotency or signature checks.Why trust the webhook over the Checkout success redirect?
The redirect only fires if the customer's browser reaches it. A closed tab, a flaky connection, or a payment that settles after a delay all mean the redirect can be skipped while the payment still succeeds — the webhook is the only event Stripe guarantees to deliver.How do I test these rules actually work?
Use the Stripe CLI to replay events locally: send a bad signature and confirm a 400, replay the same event id twice and confirm the second is a no-op, and send invoice.payment_failed to confirm the account moves to past_due without losing access immediately.
Need the full procedure, not just the bans?
Rules stop the agent from doing the wrong thing. The Stripe billing skill teaches it the right one: raw-body verification, idempotency keys, subscription sync, and a pre-launch test checklist.