Subscription Lifecycle Architect
Architect end-to-end subscription billing systems with sophisticated lifecycle management, intelligent dunning workflows, precise proration logic, and resilient payment infrastructure.
When to Use This Skill
- Architecting multi-tier subscription platforms
- Implementing intelligent dunning and retry workflows
- Designing proration strategies for plan transitions
- Building usage-based and hybrid billing models
- Selecting and integrating payment infrastructure
- Managing subscription state machines
- Optimizing billing cycle processing at scale
Core Concepts
1. Subscription State Machine
Primary States:
trialing→ Initial evaluation periodactive→ Paid and currentpast_due→ Payment failed, recovery in progresssuspended→ Temporary holdcanceled→ Permanently terminatedpaused→ User-initiated pause
Transition Rules:
trialing → active (trial ends + payment succeeds)
trialing → canceled (trial ends + no payment method)
active → past_due (payment failure)
past_due → active (dunning recovery succeeds)
past_due → canceled (dunning exhausted)
active → paused → active (user pause/resume)
2. Billing Interval Strategies
- Monthly: Standard SaaS default, predictable cash flow
- Annual: Improved retention, upfront revenue recognition
- Quarterly: Balance between commitment and flexibility
- Custom: Usage-aligned, seat-based, hybrid models
3. Dunning Workflow Architecture
Intelligent recovery process for failed payments:
- Smart Retry Scheduling: Adaptive retry intervals based on decline reason
- Customer Communication: Contextual email sequences
- Grace Period Management: Service access during recovery
- Payment Method Updates: In-recovery payment method refresh
- Final State Handling: Graceful cancellation or suspension
4. Proration Mathematics
Upgrade Mid-Cycle:
unused_credit = (days_remaining / total_days) × old_plan_price
new_charge = (days_remaining / total_days) × new_plan_price
net_charge = new_charge - unused_credit
Seat Addition:
prorated_charge = (seats_added × price_per_seat × days_remaining) / total_days
Implementation Guide
Billing Engine Core
from datetime import datetime, timedelta
from decimal import Decimal
from enum import Enum
class SubscriptionState(Enum):
TRIALING = "trialing"
ACTIVE = "active"
PAST_DUE = "past_due"
SUSPENDED = "suspended"
CANCELED = "canceled"
PAUSED = "paused"
class BillingEngine:
def __init__(self, payment_gateway):
self.gateway = payment_gateway
self.dunning_manager = DunningManager()
self.proration_calculator = ProrationCalculator()
def process_billing_cycle(self, subscription):
"""Execute billing cycle for subscription."""
if not self._is_billing_due(subscription):
return
# Generate invoice
invoice = self._generate_invoice(subscription)
# Attempt charge
payment_result = self.gateway.charge(
customer_id=subscription.customer_id,
amount=invoice.total,
idempotency_key=f"sub_{subscription.id}_invoice_{invoice.id}"
)
if payment_result.success:
self._handle_successful_payment(subscription, invoice, payment_result)
else:
self._handle_failed_payment(subscription, invoice, payment_result)
def _generate_invoice(self, subscription):
"""Generate invoice with line items and tax."""
invoice = Invoice(
subscription_id=subscription.id,
customer_id=subscription.customer_id,
billing_period_start=subscription.current_period_start,
billing_period_end=subscription.current_period_end
)
# Base subscription charge
invoice.add_line_item(
description=f"{subscription.plan.name} subscription",
amount=subscription.plan.price,
quantity=subscription.quantity
)
# Usage charges if applicable
if subscription.has_metered_usage:
usage_charge = self._calculate_usage_charge(subscription)
if usage_charge > 0:
invoice.add_line_item(
description="Usage-based charges",
amount=usage_charge
)
# Apply tax
tax = self._calculate_tax(invoice.subtotal, subscription.customer)
invoice.set_tax(tax)
invoice.finalize()
return invoice
def _handle_successful_payment(self, subscription, invoice, payment_result):
"""Process successful payment."""
invoice.mark_paid(payment_result.transaction_id)
subscription.advance_period()
subscription.set_state(SubscriptionState.ACTIVE)
# Send invoice receipt
self._send_invoice_email(subscription.customer, invoice)
def _handle_failed_payment(self, subscription, invoice, payment_result):
"""Process failed payment."""
subscription.set_state(SubscriptionState.PAST_DUE)
# Initiate dunning workflow
self.dunning_manager.start_recovery(
subscription=subscription,
invoice=invoice,
decline_code=payment_result.decline_code
)
Intelligent Dunning Manager
class DunningManager:
def __init__(self):
self.retry_schedules = {
'insufficient_funds': [3, 7, 14], # Days between retries
'card_declined': [1, 3, 7],
'expired_card': [1, 3],
'do_not_honor': [7, 14],
'generic_decline': [3, 7, 14]
}
def start_recovery(self, subscription, invoice, decline_code):
"""Initialize dunning process."""
retry_schedule = self._get_retry_schedule(decline_code)
dunning_attempt = DunningAttempt(
subscription_id=subscription.id,
invoice_id=invoice.id,
decline_code=decline_code,
retry_schedule=retry_schedule,
current_attempt=0
)
# Send initial notification
self._send_dunning_notification(
subscription.customer,
template='payment_failed_initial',
invoice=invoice
)
# Schedule first retry
self._schedule_retry(dunning_attempt, retry_schedule[0])
def execute_retry(self, dunning_attempt):
"""Execute scheduled payment retry."""
subscription = self._get_subscription(dunning_attempt.subscription_id)
invoice = self._get_invoice(dunning_attempt.invoice_id)
# Retry payment
result = self.gateway.charge(
customer_id=subscription.customer_id,
amount=invoice.total,
idempotency_key=f"retry_{dunning_attempt.id}_{dunning_attempt.current_attempt}"
)
if result.success:
self._recovery_succeeded(subscription, invoice, dunning_attempt)
else:
self._recovery_continues(subscription, dunning_attempt, result)
def _recovery_succeeded(self, subscription, invoice, dunning_attempt):
"""Handle successful recovery."""
invoice.mark_paid()
subscription.set_state(SubscriptionState.ACTIVE)
subscription.advance_period()
dunning_attempt.mark_resolved()
self._send_dunning_notification(
subscription.customer,
template='payment_recovered'
)
def _recovery_continues(self, subscription, dunning_attempt, result):
"""Handle continued failure."""
dunning_attempt.current_attempt += 1
if dunning_attempt.current_attempt < len(dunning_attempt.retry_schedule):
# Schedule next retry
next_retry_days = dunning_attempt.retry_schedule[dunning_attempt.current_attempt]
self._schedule_retry(dunning_attempt, next_retry_days)
# Send escalation email
self._send_dunning_notification(
subscription.customer,
template=f'payment_failed_attempt_{dunning_attempt.current_attempt}'
)
else:
# Retries exhausted
self._dunning_failed(subscription, dunning_attempt)
def _dunning_failed(self, subscription, dunning_attempt):
"""Handle dunning failure."""
subscription.set_state(SubscriptionState.CANCELED)
subscription.canceled_at = datetime.utcnow()
dunning_attempt.mark_failed()
self._send_dunning_notification(
subscription.customer,
template='subscription_canceled_nonpayment'
)
Proration Calculator
class ProrationCalculator:
@staticmethod
def calculate_plan_change(current_plan, new_plan, period_start, period_end, change_date):
"""Calculate proration for plan upgrade/downgrade."""
total_seconds = (period_end - period_start).total_seconds()
used_seconds = (change_date - period_start).total_seconds()
remaining_seconds = (period_end - change_date).total_seconds()
# Unused portion of current plan
current_daily_rate = current_plan.price / Decimal(total_seconds)
unused_amount = current_daily_rate * Decimal(remaining_seconds)
# Prorated charge for new plan
new_daily_rate = new_plan.price / Decimal(total_seconds)
new_plan_charge = new_daily_rate * Decimal(remaining_seconds)
# Net charge (negative = credit)
net_charge = new_plan_charge - unused_amount
return {
'current_plan_credit': unused_amount,
'new_plan_charge': new_plan_charge,
'net_proration': net_charge,
'proration_date': change_date,
'effective_immediately': True
}
@staticmethod
def calculate_quantity_change(price_per_unit, current_qty, new_qty, period_start, period_end, change_date):
"""Calculate proration for quantity changes (seats, licenses)."""
if new_qty <= current_qty:
# Downgrade: no immediate refund, credit at next renewal
return {
'immediate_charge': Decimal('0.00'),
'credit_at_renewal': (current_qty - new_qty) * price_per_unit,
'effective_next_period': True
}
# Upgrade: immediate prorated charge
total_seconds = (period_end - period_start).total_seconds()
remaining_seconds = (period_end - change_date).total_seconds()
additional_units = new_qty - current_qty
daily_rate = price_per_unit / Decimal(total_seconds)
prorated_charge = daily_rate * Decimal(remaining_seconds) * additional_units
return {
'immediate_charge': prorated_charge,
'additional_units': additional_units,
'effective_immediately': True
}
Tax Calculation Engine
class TaxEngine:
def __init__(self):
# Regional tax rates
self.tax_database = {
'US_CA': {'rate': Decimal('0.0725'), 'type': 'sales_tax'},
'US_NY': {'rate': Decimal('0.04'), 'type': 'sales_tax'},
'US_TX': {'rate': Decimal('0.0625'), 'type': 'sales_tax'},
'GB': {'rate': Decimal('0.20'), 'type': 'vat'},
'DE': {'rate': Decimal('0.19'), 'type': 'vat'},
'FR': {'rate': Decimal('0.20'), 'type': 'vat'},
'AU': {'rate': Decimal('0.10'), 'type': 'gst'},
}
def calculate(self, amount, customer):
"""Calculate applicable tax."""
jurisdiction = self._determine_jurisdiction(customer)
if not jurisdiction or jurisdiction not in self.tax_database:
return {
'tax_amount': Decimal('0.00'),
'tax_rate': Decimal('0.00'),
'jurisdiction': None,
'tax_type': None
}
tax_config = self.tax_database[jurisdiction]
tax_amount = amount * tax_config['rate']
return {
'tax_amount': tax_amount.quantize(Decimal('0.01')),
'tax_rate': tax_config['rate'],
'jurisdiction': jurisdiction,
'tax_type': tax_config['type']
}
def _determine_jurisdiction(self, customer):
"""Determine tax jurisdiction."""
if customer.country == 'US':
return f"US_{customer.state}"
elif customer.country in ['GB', 'DE', 'FR', 'AU']:
return customer.country
return None
Best Practices
- Idempotency: All payment operations must use idempotency keys to prevent duplicate charges during retries
- Audit Logging: Maintain immutable event logs for all billing state transitions, payment attempts, and refunds
- Graceful Degradation: Design subscription access controls to handle grace periods during payment recovery
- Proactive Communication: Notify customers before charging, when charges succeed, and immediately when charges fail
- Flexible Recovery: Adapt dunning schedules based on decline codes and customer segment
- Precise Proration: Use second-level precision for proration calculations to ensure fairness
- Tax Compliance: Validate tax jurisdiction logic against current regulations; consider tax automation services
- Webhook Resilience: Implement exponential backoff and dead-letter queues for payment gateway webhooks
- Testing Rigor: Test edge cases including plan changes during trials, concurrent upgrades, and timezone boundaries
Common Pitfalls
- Naive Retry Logic: Using fixed retry schedules regardless of decline reason
- Timezone Errors: Not normalizing billing dates to UTC for global customers
- Rounding Inconsistencies: Losing fractions of cents across multiple proration calculations
- Missing Idempotency: Creating duplicate charges when retrying failed API calls
- Hardcoded Tax Rates: Not updating tax rates when regulations change
- Insufficient Grace Periods: Canceling access immediately on first payment failure
- Weak Dunning Communication: Failing to explain payment issues clearly to customers
- No Payment Method Updates: Not allowing customers to update cards during dunning
- Ignoring Subscription Pauses: Not handling user-initiated pause/resume flows
- Poor Webhook Handling: Losing payment events due to unhandled webhook failures
Advanced Patterns
Usage-Based Billing
class MeteredBillingEngine:
def track_event(self, customer_id, metric_name, quantity, timestamp=None):
"""Record metered usage event."""
UsageEvent.create(
customer_id=customer_id,
metric=metric_name,
quantity=quantity,
timestamp=timestamp or datetime.utcnow()
)
def calculate_period_usage(self, subscription, period_start, period_end):
"""Calculate total usage charges for period."""
events = UsageEvent.query(
customer_id=subscription.customer_id,
timestamp__gte=period_start,
timestamp__lt=period_end
)
total_quantity = sum(e.quantity for e in events)
# Apply pricing model
if subscription.pricing_model == 'tiered':
return self._apply_tiered_pricing(total_quantity, subscription.tiers)
elif subscription.pricing_model == 'volume':
return self._apply_volume_pricing(total_quantity, subscription.tiers)
elif subscription.pricing_model == 'per_unit':
return total_quantity * subscription.unit_price
Hybrid Subscription Models
Combine fixed subscription fees with usage-based charges:
class HybridBillingEngine:
def generate_hybrid_invoice(self, subscription, period_start, period_end):
"""Generate invoice with base + usage components."""
invoice = Invoice(subscription_id=subscription.id)
# Base subscription fee
invoice.add_line_item(
description=f"{subscription.plan.name} (base)",
amount=subscription.plan.base_price
)
# Metered usage charges
usage_charge = self.metered_engine.calculate_period_usage(
subscription, period_start, period_end
)
if usage_charge > 0:
invoice.add_line_item(
description="Usage charges",
amount=usage_charge
)
# Apply tax and finalize
tax = self.tax_engine.calculate(invoice.subtotal, subscription.customer)
invoice.set_tax(tax['tax_amount'])
invoice.finalize()
return invoice
Resources
- references/subscription-state-machines.md: Comprehensive state transition rules
- references/dunning-optimization.md: Adaptive retry scheduling strategies
- references/proration-edge-cases.md: Handling complex proration scenarios
- references/tax-nexus-rules.md: Sales tax and VAT nexus determination
- references/payment-gateway-comparison.md: Gateway feature comparison matrix
- assets/billing-workflow.yaml: Event-driven billing architecture
- assets/dunning-templates/: Customer notification email templates
- assets/invoice-pdf-generator.py: Invoice PDF generation utilities
Integration Examples
Stripe Integration
import stripe
class StripeGateway:
def __init__(self, api_key):
stripe.api_key = api_key
def charge(self, customer_id, amount, idempotency_key):
"""Charge customer using saved payment method."""
try:
charge = stripe.Charge.create(
customer=customer_id,
amount=int(amount * 100), # Convert to cents
currency='usd',
idempotency_key=idempotency_key
)
return PaymentResult(
success=True,
transaction_id=charge.id
)
except stripe.error.CardError as e:
return PaymentResult(
success=False,
decline_code=e.code,
error_message=str(e)
)
PayPal Integration
from paypalrestsdk import Payment
class PayPalGateway:
def __init__(self, client_id, client_secret):
self.client_id = client_id
self.client_secret = client_secret
def charge(self, customer_id, amount, idempotency_key):
"""Execute payment via PayPal."""
# Implementation details
pass