Foundation

The Stripe Billing Playbook

Customer linkage, plan tiers, a webhook handler that survives replays, and checkout.

STRIPE-BILLING-PLAYBOOK.md · 15 sections · 2,392 words · 20 KB · markdown

The whole money layer. Stripe customer linkage to your user table, plan-tier modeling, an idempotent webhook handler, checkout sessions, and the founding-member pattern for pre-launch pricing. Written around the failure modes — duplicate events, out-of-order webhooks, subscription drift.

What's inside

//Stripe customer ↔ user linkage that can't drift
//Plan tier modeling (free / founding / paid / agency)
//An idempotent webhook handler with an event-dedupe table
//Checkout session creation + the return-URL contract
//The founding-member pattern for pre-launch pricing
//Subscription-state reconciliation when webhooks are missed

When to use it

Week 2, once there's something worth charging for.

Build these first

App Infrastructure, Auth & Onboarding

Unlocks

Credit Metering, Affiliate Program

Straight from the file

Pairs with AUTH-ONBOARDING-PLAYBOOK.md (depends on profiles.account_status) and EMAIL-INFRA-PLAYBOOK.md (consumes subscription_canceled / payment_failed trigger events).

Table of contents

0. Use this spec
1. Architecture
2. Schema
3. The webhook handler — the load-bearing file
4. Checkout + portal
5. Plan-gated feature enforcement
6. Credit allocation pattern
7. Payment failed → accountstatus
8. Email triggers (cross-reference)
9. Founding-member / lifetime-pricing pattern
10. Downgrade handling
11. Refund flow
12. Common pitfalls
13. Kickoff prompt
14. Reference files in BKE

How to run it

Drop STRIPE-BILLING-PLAYBOOK.md into your repo, then tell Claude Code: “Read STRIPE-BILLING-PLAYBOOK.md and implement it in this codebase.” It's written for an agent to execute end to end. Search the file for angle-bracket placeholders and swap in your own project names, domains, and keys before the first run.

↓ Download the playbook

More foundation playbooks

S-tier

← All 28 Claude templates