Stripe Billing

Implement subscriptions, invoicing, and flexible pricing models for recurring revenue.

Rule Priority

Pricing Model Decision Tree

What pricing model fits your product?
|
+-- Fixed monthly/annual fee?
|   -> Flat-rate pricing (references/pricing-models.md)
|
+-- Per-seat / per-unit?
|   -> Per-unit pricing (references/pricing-models.md)
|
+-- Volume tiers (price decreases with quantity)?
|   -> Tiered pricing (references/pricing-models.md)
|
+-- Pay for what you use (API calls, storage)?
|   -> Usage-based / metered (references/usage-based.md)
|
+-- Hybrid (base fee + usage)?
    -> Multiple prices on one subscription (references/pricing-models.md)

Quick Start: SaaS Subscription

1. Create Product + Price (once, or via Dashboard)

const product = await stripe.products.create({
  name: 'Pro Plan',
  description: 'Full access to all features',
});

const price = await stripe.prices.create({
  product: product.id,
  unit_amount: 2900, // $29/month
  currency: 'usd',
  recurring: { interval: 'month' },
  lookup_key: 'pro_monthly',
});

2. Create Subscription via Checkout

const session = await stripe.checkout.sessions.create({
  customer: 'cus_xxx', // or let Checkout create one
  line_items: [{ price: price.id, quantity: 1 }],
  mode: 'subscription',
  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/cancel',
});

3. Or Create Subscription Directly (with existing payment method)

const subscription = await stripe.subscriptions.create({
  customer: 'cus_xxx',
  items: [{ price: price.id }],
  default_payment_method: 'pm_xxx',
  payment_behavior: 'default_incomplete', // requires client confirmation
  expand: ['latest_invoice.payment_intent'],
});
// Return subscription.latest_invoice.payment_intent.client_secret to frontend

Subscription Lifecycle

incomplete -> active -> past_due -> canceled
                     -> canceled (immediate)
                     -> paused
trialing -> active (payment succeeds)
        -> incomplete (payment fails)
        -> canceled (trial ends, no payment method)

Customer Portal (Self-Service)

// One-time setup in Dashboard or API
const configuration = await stripe.billingPortal.configurations.create({
  features: {
    subscription_update: { enabled: true, products: [{ product: 'prod_xxx', prices: ['price_basic', 'price_pro'] }] },
    subscription_cancel: { enabled: true, mode: 'at_period_end' },
    payment_method_update: { enabled: true },
    invoice_history: { enabled: true },
  },
});

// Generate portal session per customer
const portalSession = await stripe.billingPortal.sessions.create({
  customer: 'cus_xxx',
  return_url: 'https://example.com/account',
});
// Redirect to portalSession.url

Critical Webhooks

Quick Reference

References

• references/pricing-models.md - Flat, tiered, per-unit, graduated, volume pricing
• references/subscription-lifecycle.md - Create, update, cancel, pause, resume
• references/usage-based.md - Metered billing, usage records, aggregation
• references/trials.md - Free trials with/without payment method, trial conversions
• references/invoices.md - Invoice generation, customization, hosted page
• references/customer-portal.md - Self-service configuration and customization
• references/dunning.md - Smart retries, failed payment emails, recovery
• references/coupons.md - Coupons, promotion codes, discounts
• references/proration.md - Mid-cycle upgrades/downgrades, proration behavior
• references/schedules.md - Subscription schedules for future changes