# Stripe Billing Skill for Cursor

> A Cursor Stripe skill for the failure modes agents hit most: Checkout sessions created without metadata, webhook signatures verified against a parsed body, duplicate events applied twice, and subscription state that drifts from Stripe. Ends with a test checklist to run before you take real payments.

Canonical: https://www.agentickit.co/skills/stripe-billing-webhooks
Last updated: 2026-11-18

## Key practices
- Read the webhook body with request.text() before any JSON parsing, then pass that raw string to stripe.webhooks.constructEvent; a re-serialized body fails verification
- Store the Stripe event ID in a unique-constrained table and insert it before side effects, so a retried delivery is a no-op instead of a second upgrade
- Treat the database as a cache of Stripe: update plan, status, and current_period_end from customer.subscription.created/updated/deleted, never from the Checkout success redirect
- Pass client_reference_id and metadata (user or org ID) when creating the Checkout session so checkout.session.completed can be tied to an account without matching on email
- Return 2xx quickly and push slow work to a queue; handle out-of-order events by re-fetching the object from Stripe instead of trusting the event payload alone
- Keep separate test-mode and live-mode webhook secrets per environment and fail loudly at boot if STRIPE_WEBHOOK_SECRET is missing
- Test checklist: bad signature returns 400, replayed event ID changes nothing, payment_failed moves the account to past_due, cancel at period end keeps access until the period ends, and the Stripe CLI can replay each event locally
- Before launch, run the free security scan tool on your deployed URL to catch exposed keys or missing headers around the billing routes

## Related
- [integration-engineer](https://www.agentickit.co/agents/integration-engineer)
- [backend-architect](https://www.agentickit.co/agents/backend-architect)
- [security-auditor](https://www.agentickit.co/agents/security-auditor)
- [/stripe-billing](https://www.agentickit.co/commands/stripe-billing)
- [/audit](https://www.agentickit.co/commands/audit)
