billing
Billing - Stripe, webhooks, subscriptions. Use when implementing payments.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for implementing robust billing systems using Stripe. It focuses on secure webhook integration, subscription management, and financial data integrity. By enforcing best practices like webhook signature verification and idempotency, it ensures a reliable payment experience while preventing common pitfalls such as duplicate charges or out-of-order event processing.
Use Cases
- Implementing Stripe Subscriptions: Guide the setup of recurring billing cycles while ensuring the system remains synchronized with Stripe events.
- Secure Webhook Integration: Establish a secure communication channel between Stripe and your backend by verifying signatures and handling asynchronous event delivery.
- Idempotency and Error Handling: Prevent duplicate transactions and financial discrepancies by using Stripe event IDs to manage state transitions safely.
- Billing Architecture Design: Build a scalable billing engine that treats Stripe as the single source of truth, minimizing data synchronization issues and dual-write conflicts.
| name | billing |
|---|---|
| description | Billing - Stripe, webhooks, subscriptions. Use when implementing payments. |
Billing Guideline
Tech Stack
- Payments: Stripe
- Workflows: Upstash Workflows + QStash
Non-Negotiables
- Webhook signature must be verified (reject unverifiable events)
- Stripe event ID must be used for idempotency
- Webhooks must handle out-of-order delivery
- No dual-write: billing truth comes from Stripe events only
- UI must only display states derivable from server-truth
Context
Billing is where trust meets money. A bug here isn't just annoying — it's a financial and legal issue. Users must always see accurate state, and the system must never lose or duplicate charges.
Beyond correctness, consider the user experience of billing. Is the upgrade path frictionless? Are failed payments handled gracefully? Does the dunning process recover revenue or just annoy users?
Driving Questions
- What happens when webhooks arrive out of order?
- Where could revenue leak (failed renewals, unhandled states)?
- What billing states are confusing to users?
- How are disputes and chargebacks handled end-to-end?
- If Stripe is temporarily unavailable, what breaks?
- What would make the billing experience genuinely excellent?