stripe_billing_integration v1.0.0

name: stripe_billing_integration description: > Implement Stripe subscription billing end to end: Checkout, the subscription lifecycle webhooks, dunning with Smart Retries, and time-travel testing with test clocks. Use when wiring paid tiers, handling failed renewals, setting up the Customer Portal, or debugging billing events.

Stripe Billing Integration

Purpose

Ship the production billing patterns Stripe integrations need but most tutorials skip: the full subscription lifecycle, webhook handling done safely, retry and dunning behavior that actually recovers failed payments, and a test strategy that covers trials, renewals, and proration without waiting 30 days.

Workflow

1. Pick the integration shape. Checkout (Stripe-hosted) for the fastest reliable path; Payment Element when the checkout page must be custom. For self-service plan changes and card updates, use the Customer Portal, never build your own.
2. Build the webhook handler first, fulfillment second. Register an endpoint, verify signatures with the raw body, and route events before writing any access-grant logic. Fulfillment that exists before the handler exists is how double-grant and never-grant bugs ship.
3. Map Stripe subscription status to access. trialing and active mean provisioned. past_due means keep access during the grace window and run dunning, not a lockout. canceled, unpaid, and incomplete_expired mean revoke. incomplete means never provision.
4. Subscribe to the minimum event set that covers the lifecycle: checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.paid, invoice.payment_failed, invoice.payment_action_required, customer.subscription.trial_will_end. See references/billing-webhooks.md for the event matrix and the raw-body verification code.
5. Make the handler idempotent and order-safe. Dedup on event.id (Stripe retries non-2xx deliveries for up to about 3 days). Events can arrive out of order, so when two events disagree about a subscription, re-read its current state from the Stripe API instead of trusting whichever event arrived last.
6. Configure Smart Retries and dunning. Stripe's recommended default is 8 retries within 2 weeks; during retries the subscription sits in past_due, and when retries run out the subscription moves to the end state you configured (usually unpaid or canceled). Pair this with your own reminder emails that link the customer to the Customer Portal. Details and the decline-code taxonomy are in references/dunning.md.
7. Test with test clocks, not wall-clock waits. Create a clock, attach test customers to it, and advance it to hit trial end, renewal, failed renewal, and proration scenarios in minutes. Recipes are in references/test-clocks.md. For quick smoke tests without clocks, use the Stripe CLI: stripe trigger invoice.payment_failed and stripe listen --forward-to http://localhost:3000/webhooks/stripe.

Output Contract

A Stripe billing integration that:

• Creates customers and subscriptions through Checkout or Payment Element with the subscription and price IDs stored locally
• Handles the 8 core lifecycle events with signature verification, idempotency, and a 2xx response fast enough that Stripe never needs to retry
• Keeps access in sync with subscription status per the mapping above, including a past-due grace window
• Recovers failed payments through Smart Retries plus customer outreach, not lockouts on first failure
• Has test-clock coverage for trial-to-active, successful renewal, failed renewal through dunning to the end state, and mid-cycle proration

Operating Rules

• Verify every webhook signature with the raw, unparsed request body (stripe.webhooks.constructEvent(rawBody, sig, endpointSecret)). A body that was parsed and re-serialized will fail verification, because the bytes differ from what Stripe signed. On failure return HTTP 400, never 500.
• Never grant or revoke access from success_url. It is a display page, and users can visit it without paying. Webhooks are the only fulfillment source.
• The amount on checkout.session.completed is amount_total in cents. Not amount, not total.
• For mid-cycle upgrades use proration_behavior: 'create_prorations'. Never compute prorations by hand.
• On the subscription object, default_payment_method wins over the customer's default when retries charge. If you update one, make sure it is the one retries use.
• Retry logic follows the decline code: soft declines (insufficient_funds, do_not_honor, processing_error) are worth retrying, hard declines (lost_card, stolen_card, card_not_supported) are not, and authentication_required (3DS/SCA) never self-resolves, so it goes straight to customer action.
• Test keys are the only keys used outside production. Secret keys never touch client-side code or version control.