Stripe Billing & Subscriptions Expert

Purpose

Specialized expertise in Stripe's billing and subscription systems. Covers all aspects of recurring revenue, subscription management, usage-based billing, invoicing, and financial operations.

Documentation Base

Location: /Users/zach/Documents/cc-skills/docs/stripe/

Key Sections:

• billing/ - Core billing documentation (124+ files)
• billing/subscriptions/ - Subscription management
• billing/subscriptions/usage-based/ - Metered & usage-based billing
• revenue-recognition/ - Revenue reporting (50+ files)
• api/subscriptions/ - Subscription API reference
• api/invoices/ - Invoice API reference
• api/prices/ - Pricing API
• customer-management/ - Customer portal & management

Core Capabilities

1. Subscription Models

• Fixed pricing - Monthly/annual subscriptions
• Tiered pricing - Volume-based tiers
• Volume pricing - Price per unit
• Graduated pricing - Tier-based unit pricing
• Package pricing - Bundled units
• Usage-based - Metered billing (API calls, seats, etc.)
• Hybrid models - Base fee + usage

2. Subscription Lifecycle

• Creation & activation
• Trial periods & conversions
• Upgrades & downgrades
• Prorations & billing adjustments
• Pausing & resuming
• Cancellations & retention
• Backdating subscriptions

3. Invoicing

• Automatic invoice generation
• Manual invoices
• Invoice customization
• Payment collection
• Dunning management
• Failed payment recovery
• Invoice finalization

4. Usage-Based Billing

• Meter events (API-based metering)
• Aggregation methods (sum, max, last)
• Billing thresholds
• Usage reporting & analytics
• Billing credits
• Grace periods

5. Revenue Recognition

• ASC 606 & IFRS 15 compliance
• Deferred revenue tracking
• Revenue schedules
• Multi-currency handling
• Performance obligations

Common Patterns

Basic Subscription

// Create customer with payment method
const customer = await stripe.customers.create({
  email: 'user@example.com',
  payment_method: paymentMethodId,
  invoice_settings: {
    default_payment_method: paymentMethodId,
  },
});

// Create subscription
const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{
    price: 'price_monthly_pro', // Price ID from dashboard
  }],
  expand: ['latest_invoice.payment_intent'],
});

Usage-Based Subscription

// 1. Create meter (one-time, in Dashboard or API)
const meter = await stripe.billing.meters.create({
  display_name: 'API Requests',
  event_name: 'api_request',
  default_aggregation: {
    formula: 'sum',
  },
});

// 2. Create price based on meter
const price = await stripe.prices.create({
  currency: 'usd',
  recurring: {
    interval: 'month',
    usage_type: 'metered',
  },
  billing_scheme: 'per_unit',
  unit_amount_decimal: '0.01', // $0.01 per request
  product_data: {
    name: 'API Usage',
  },
});

// 3. Create subscription
const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: price.id }],
});

// 4. Report usage
await stripe.billing.meterEvents.create({
  event_name: 'api_request',
  payload: {
    stripe_customer_id: customerId,
    value: '1', // 1 API request
  },
});

Subscription with Trial

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
  trial_period_days: 14, // 14-day free trial
  trial_settings: {
    end_behavior: {
      missing_payment_method: 'cancel', // Cancel if no payment method at trial end
    },
  },
});

Proration on Upgrade/Downgrade

// Upgrade subscription
const subscription = await stripe.subscriptions.update(subscriptionId, {
  items: [{
    id: subscriptionItemId,
    price: 'price_premium', // New price tier
  }],
  proration_behavior: 'create_prorations', // Pro-rate the difference
  billing_cycle_anchor: 'unchanged', // Keep original billing cycle
});

Subscription Schedules (Future Changes)

const schedule = await stripe.subscriptionSchedules.create({
  customer: customerId,
  start_date: 'now',
  end_behavior: 'release',
  phases: [
    {
      items: [{ price: 'price_starter' }],
      iterations: 3, // 3 billing cycles
    },
    {
      items: [{ price: 'price_pro' }],
      // Continues indefinitely
    },
  ],
});

Handle Failed Payments

// Webhook handler
if (event.type === 'invoice.payment_failed') {
  const invoice = event.data.object;
  
  // Get subscription
  const subscription = await stripe.subscriptions.retrieve(
    invoice.subscription
  );
  
  if (subscription.status === 'past_due') {
    // Send notification to customer
    await sendPaymentFailedEmail(invoice.customer_email);
    
    // Optionally pause service
    await pauseUserAccess(invoice.customer);
  }
}

Customer Portal Integration

// Create portal session
const session = await stripe.billingPortal.sessions.create({
  customer: customerId,
  return_url: 'https://example.com/account',
});

// Redirect user to session.url
// Customers can:
// - Update payment methods
// - View invoices
// - Manage subscriptions
// - Download receipts

Advanced Patterns

Multi-Plan Subscription

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [
    { price: 'price_base_plan' },
    { price: 'price_addon_1' },
    { price: 'price_addon_2' },
  ],
});

Billing Anchors

// Anchor billing to specific day of month
const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
  billing_cycle_anchor: Math.floor(
    new Date('2024-01-15').getTime() / 1000
  ), // Bill on 15th of each month
  proration_behavior: 'none',
});

Subscription Metadata for Tracking

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
  metadata: {
    internal_user_id: 'user_12345',
    plan_name: 'Professional',
    signup_source: 'landing_page_a',
    affiliate_id: 'aff_789',
  },
});

Subscription States

Invoice Lifecycle

1. draft - Invoice created, not finalized
2. open - Finalized, awaiting payment
3. paid - Successfully paid
4. void - Canceled/voided
5. uncollectible - Marked as bad debt

Best Practices

1. Use Price objects (not deprecated Plans)
2. Enable Smart Retries for failed payments
3. Implement dunning logic via webhooks
4. Test trial-to-paid conversions thoroughly
5. Use subscription schedules for future changes
6. Implement customer portal for self-service
7. Monitor subscription metrics (MRR, churn, LTV)
8. Handle prorations correctly on plan changes
9. Set up invoice.paid webhooks for fulfillment
10. Use metadata for internal tracking

Key Webhooks

// Essential subscription webhooks
const subscriptionEvents = [
  'customer.subscription.created',
  'customer.subscription.updated',
  'customer.subscription.deleted',
  'customer.subscription.trial_will_end', // 3 days before trial ends
  'customer.subscription.paused',
  'customer.subscription.resumed',
  
  'invoice.created',
  'invoice.finalized',
  'invoice.paid',
  'invoice.payment_failed',
  'invoice.payment_action_required', // 3D Secure needed
  
  'payment_intent.succeeded',
  'payment_intent.payment_failed',
];

Testing Scenarios

1. Successful subscription creation
2. Trial period behavior
3. Upgrade/downgrade with prorations
4. Failed payment scenarios
5. Dunning and retries
6. Cancellation and reactivation
7. Usage reporting accuracy
8. Invoice generation timing
9. Multi-currency subscriptions
10. Customer portal flows

Common Issues & Solutions

Issue: Proration Confusion

Solution: Use proration_behavior parameter:

• create_prorations - Generate credit/charge for time difference
• none - No proration
• always_invoice - Create invoice immediately

Issue: Trial Ends But No Payment Method

Solution: Use trial_settings.end_behavior.missing_payment_method = 'cancel'

Issue: Multiple Failed Payments

Solution: Implement Smart Retries + custom dunning logic via webhooks

Issue: Revenue Recognition Timing

Solution: Use Stripe Revenue Recognition product or implement custom logic based on invoice.finalized events

Metrics to Monitor

• MRR (Monthly Recurring Revenue)
• ARR (Annual Recurring Revenue)
• Churn Rate
• Upgrade/Downgrade Rates
• Trial Conversion Rate
• Payment Success Rate
• Dunning Recovery Rate
• Customer Lifetime Value (LTV)
• Average Revenue Per User (ARPU)

Documentation Quick Links

# Find subscription docs
grep -r "subscription" docs/stripe/billing/subscriptions/

# Find usage-based billing
ls docs/stripe/billing/subscriptions/usage-based/

# Find invoice docs
grep -r "invoice" docs/stripe/api/invoices/

# Find proration examples
grep -r "proration" docs/stripe/billing/

# Find customer portal docs
ls docs/stripe/customer-management/

Reference

All code examples follow Stripe API version 2023-10+. For implementation details, consult:

• /docs/stripe/billing/ - Billing fundamentals
• /docs/stripe/billing/subscriptions/ - Subscription guides
• /docs/stripe/revenue-recognition/ - Revenue tracking
• /docs/stripe/api/subscriptions/ - API reference