# Cursor Rules for Stripe & Billing Codebases

> Four glob-scoped Cursor rules for Stripe-heavy repos: webhook verification, idempotent handlers, subscription state, and secret hygiene. Copy-paste .mdc files plus when to graduate a rule into the Stripe billing skill.

Canonical: https://www.agentickit.co/compare/cursor-rules-for-stripe
Last updated: 2026-11-18

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](https://www.agentickit.co/compare/cursor-rules-vs-skills).

## 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](https://www.agentickit.co/skills/stripe-billing-webhooks) covers exactly that, and the [/stripe-billing command](https://www.agentickit.co/commands/stripe-billing) runs the full setup in one pass using these rules as guardrails.



## FAQ

### 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.

## Related
- [Stripe billing skill (Checkout, webhooks, subscription sync)](https://www.agentickit.co/skills/stripe-billing-webhooks)
- [Claude Code Stripe webhooks setup guide](https://www.agentickit.co/blog/claude-code-stripe-webhooks-setup)
- [/stripe-billing command](https://www.agentickit.co/commands/stripe-billing)
- [Stripe payments skill](https://www.agentickit.co/skills/stripe-payments)
- [Best Cursor rules in 2026](https://www.agentickit.co/blog/best-cursor-rules-2026)
- [Cursor rules for SaaS founders](https://www.agentickit.co/blog/cursor-rules-saas-founders)
- [Cursor Rules vs Skills vs Commands](https://www.agentickit.co/compare/cursor-rules-vs-skills)
- [Rules File Grader](https://www.agentickit.co/tools/rules-grader)
