Subscription Billing (Stripe)
Managing recurring payment cycles using Stripe's Subscription and Price APIs, including plan creation, billing intervals, upgrades/downgrades, and lifecycle event handling.
Description
Stripe's subscription billing system revolves around Products, Prices, and Subscriptions. A Product represents what you sell (e.g., 'Pro Plan'), a Price defines how much and how often to charge (e.g., $29/month), and a Subscription ties a Customer to one or more Prices with a specific billing cycle. Subscriptions automatically generate Invoices at each billing period, attempt payment collection, and emit webhook events for every state transition. Your application should treat these webhook events as the source of truth for subscription status rather than polling the API.
Subscription statuses follow a defined lifecycle: incomplete (initial payment pending), active, past_due (payment failed but retrying), unpaid (retries exhausted), canceled, or trialing. Each status transition triggers specific webhook events (customer.subscription.created, customer.subscription.updated, customer.subscription.deleted) that your application must handle to keep its internal access control synchronized. The subscription_data.metadata field should carry your internal plan identifiers to simplify webhook processing.
Advanced subscription features include multi-price subscriptions (bundling multiple line items), metered billing (reporting usage via the Usage Record API), billing anchors (normalizing billing dates), and subscription schedules (pre-programming future plan changes). Collection methods can be charge_automatically (default) or send_invoice for enterprise customers who pay via wire transfer with net-30 terms.
Prompt Snippet
Model your pricing as Stripe Products with multiple Prices (monthly/annual) created via the API or Dashboard, storing the price_id in your plans config rather than hardcoding amounts. Create subscriptions with stripe.subscriptions.create() setting payment_behavior to 'default_incomplete' to handle SCA authentication via the returned pending SetupIntent. Sync subscription state by processing customer.subscription.updated webhooks, keying off subscription.status and current_period_end to gate feature access. Use billing_cycle_anchor and proration_behavior: 'create_prorations' for mid-cycle plan changes.
Tags
Related Terms
Usage-Based Billing
A billing model where customers are charged based on their actual consumption of resources or API calls, tracked via usage records reported to the billing system.
Proration for Plan Changes
Calculating the proportional credit or charge when a customer upgrades or downgrades their subscription plan mid-billing cycle, ensuring fair billing for the time spent on each plan.
Free Trial Implementation
Implementing time-limited free access to paid features using Stripe's subscription trial periods, including card collection strategy, trial expiration handling, and conversion optimization.
Failed Payment Recovery (Dunning)
The systematic process of recovering failed subscription payments through automated retries, customer communications, and graceful degradation before eventually canceling the subscription.
Coupon/Discount System
Implementing promotional pricing through Stripe's Coupon and Promotion Code APIs, supporting percentage and fixed-amount discounts with configurable duration, redemption limits, and eligibility rules.
Invoice Generation
Creating and managing invoices for one-time charges and subscription billing cycles, including line item customization, tax itemization, and PDF generation through Stripe's Invoice API.