Stripe Subscriptions & Billing Implementation

Subscriptions progress through various states. Your system must handle each transition.

Subscription statuses:

• trialing: Free trial period
• active: Paid and current
• past_due: Payment failed, retrying
• canceled: Ended, no more charges
• unpaid: All retries failed
• incomplete: Initial payment pending
• incomplete_expired: Initial payment failed

Key lifecycle events:

• Trial starting and ending
• Successful payment
• Failed payment and retries
• Plan changes (upgrade/downgrade)
• Cancellation and reactivation

Webhook events to handle:

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed
• customer.subscription.trial_will_end

Build your system to be event-driven. Don't poll for subscription status—react to webhook events.

When customers change plans mid-cycle, proration calculates fair charges.

Proration scenarios:

Upgrade (immediate):

• Credit for unused time on current plan
• Charge for remaining time on new plan
• Net charge (usually positive) on next invoice

Downgrade:

• Credit for unused time on current plan
• Applied to future invoices
• Or refunded (based on your policy)

Proration behaviors:

• create_prorations (default): Calculate and apply prorations
• none: No adjustment, change at next renewal
• always_invoice: Immediately invoice proration amount

Implementation example: For a user upgrading from $10/mo to $50/mo halfway through the cycle:

• Credit: $5 (unused half of $10 plan)
• Charge: $25 (half month of $50 plan)
• Net: $20 added to next invoice (or charged immediately)

Choose proration behavior based on your pricing model and customer expectations.

Payment failures are normal. Proper dunning recovers most failed payments.

Stripe's automatic retry schedule:

• First retry: 3 days after failure
• Second retry: 5 days after first retry
• Third retry: 7 days after second retry
• Configurable in Billing settings

Smart Retries: Stripe's ML predicts optimal retry times based on:

• Time of day/week
• Payment method type
• Historical success patterns

Enable Smart Retries for better recovery rates.

Customer communication:

• Automatic emails for failed payments
• Update payment method reminders
• Pre-dunning for expiring cards
• Customize email templates in Dashboard

Your implementation should:

• Downgrade features during grace period
• Show in-app payment failure notices
• Provide easy path to update payment method
• Define policy for subscription cancellation

Revenue recovery best practices:

• Send 3-4 emails before cancellation
• Offer pause instead of cancel
• Allow reactivation after cancellation
• Consider retention offers for at-risk subscribers

Stripe's Customer Portal provides self-service subscription management.

Portal capabilities:

• View subscription details
• Change plans (upgrade/downgrade)
• Update payment method
• View invoice history
• Cancel subscription

Portal configuration:

• Enable/disable features
• Define allowed plan changes
• Set cancellation flow
• Customize branding

Implementation:

1. Create portal session via API
2. Redirect customer to portal URL
3. Handle return URL after actions
4. Process resulting webhooks

Custom portal alternative: Build your own UI using Stripe API for:

• More control over UX
• Integrated with your app flow
• Custom retention flows
• Usage visibility for metered billing

Hybrid approach: Use Stripe Portal for payment method updates and invoice history. Build custom flows for plan changes where you want to add retention logic.

Operating in Europe adds requirements beyond basic Stripe Billing.

VAT handling with Stripe Tax:

• Automatic VAT calculation
• Tax-inclusive or exclusive pricing
• VAT ID validation for B2B
• Proper invoicing with tax breakdown

Invoice requirements:

• Sequential invoice numbers
• VAT number display
• Tax breakdowns by rate
• Legal entity information

SCA for subscriptions:

• SCA required for initial payment
• Stripe handles SCA during checkout
• Off-session payments (renewals) generally exempt
• Handle authentication_required status

SEPA as payment method:

• Lower fees than cards (~0.35% vs 1.5%)
• Longer settlement (3-5 days)
• Good for B2B subscriptions
• Mandate collection via Checkout

Multi-currency:

• Create prices in multiple currencies
• Or use automatic currency conversion
• Consider local pricing vs dynamic conversion