How to Build a Subscription Billing System That Scales

Key Takeaways

• Start simple: Use Stripe or a dedicated billing platform for MVP, don't build from scratch
• Handle edge cases: Proration, failed payments, and upgrades/downgrades are where most systems break
• Design for scale: Idempotency, retry logic, and async processing are non-negotiable
• Compliance matters: PCI-DSS, tax calculation, and multi-currency support become critical at scale
• Revenue recognition: ASC 606/IFRS 15 compliance is required once you hit significant revenue

The Architecture

Subscription Engine: Manages subscription lifecycle (create, update, cancel, pause)

Payment Processing: Handles card transactions, tokenization, and PCI compliance

Invoice Generation: Creates and sends invoices with line items, taxes, and discounts

Dunning Management: Automated retry logic for failed payments

Revenue Recognition: Prorates revenue over subscription periods for accounting

Example: Idempotency in Practice

// Client sends idempotency key with each mutation
const response = await stripe.subscriptions.update(
  subscriptionId,
  { plan: 'pro' },
  { idempotencyKey: 'upgrade-pro-12345' }
);

// Server validates idempotency before processing
async function handleSubscriptionUpdate(idempotencyKey, update) {
  const existing = await db.query.idempotency.find({ key: idempotencyKey });
  if (existing) return existing.result;
  
  const result = await processUpdate(update);
  await db.query.idempotency.create({ key: idempotencyKey, result });
  return result;
}

Dunning Strategy That Works

Day 0: Immediate retry with same payment method

Day 3: Email customer, offer updated payment method

Day 7: Second retry attempt

Day 14: Email with cancellation warning

Day 30: Suspend service, final retry

Day 45: Cancel subscription, mark as churned

Core Tables

-- Products and pricing
CREATE TABLE products (
  id UUID PRIMARY KEY,
  name VARCHAR(255),
  description TEXT,
  active BOOLEAN DEFAULT true
);

CREATE TABLE prices (
  id UUID PRIMARY KEY,
  product_id UUID REFERENCES products(id),
  type VARCHAR(50), -- 'recurring' or 'one-time'
  amount BIGINT, -- in smallest currency unit
  currency VARCHAR(3),
  interval VARCHAR(20), -- 'month', 'year'
  interval_count INTEGER
);

-- Customer subscriptions
CREATE TABLE subscriptions (
  id UUID PRIMARY KEY,
  customer_id UUID REFERENCES customers(id),
  status VARCHAR(50), -- 'active', 'canceled', 'past_due'
  current_period_start TIMESTAMP,
  current_period_end TIMESTAMP,
  cancel_at_period_end BOOLEAN,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Payment attempts for audit trail
CREATE TABLE payment_attempts (
  id UUID PRIMARY KEY,
  subscription_id UUID REFERENCES subscriptions(id),
  amount BIGINT,
  status VARCHAR(50), -- 'succeeded', 'failed', 'pending'
  failure_reason TEXT,
  attempt_number INTEGER,
  created_at TIMESTAMP DEFAULT NOW()
);

Async Job Processing

import { scheduleJob } from 'node-schedule';

// Run every hour to process due subscriptions
scheduleJob('0 * * * *', async () => {
  const dueSubscriptions = await db.query.subscriptions.find({
    where: {
      status: 'active',
      currentPeriodEnd: { lte: new Date() }
    }
  });

  for (const subscription of dueSubscriptions) {
    await processSubscriptionRenewal(subscription);
  }
});

async function processSubscriptionRenewal(subscription) {
  // 1. Create invoice with line items
  const invoice = await createInvoice(subscription);
  
  // 2. Attempt payment
  const payment = await processPayment(invoice);
  
  // 3. Update subscription period
  await updateSubscriptionPeriod(subscription, payment);
  
  // 4. Handle failure with dunning
  if (payment.status === 'failed') {
    await triggerDunning(subscription);
  }
}

Case Study: Michigan Sprinter Center

A vehicle dealership needed a custom subscription system for their maintenance packages. We built a SaaS billing system that handles:

• 4,000+ active subscriptions across multiple service tiers
• Automated renewal with smart retry logic
• Multi-location support for their 3 dealership locations
• Revenue tracking that integrates with their accounting software

The result: $185K in first quarter revenue from subscription services alone, with 99.7% payment success rate after dunning optimization.

Case Study: Isla Hotel Reservation Platform

For a hotel management SaaS, we implemented a subscription billing system with:

• Usage-based billing for API calls and bookings
• Seamless upgrades with automatic proration
• Multi-tenant architecture with isolated billing data

This enabled 68% reduction in front-desk calls and supported growth from 10 to 200+ hotels on the platform.

Use Stripe/Paddle When:

• You're launching an MVP or pre-seed startup
• You need to ship in 4-8 weeks
• You have standard subscription models
• Team size is under 10 engineers

Build Custom When:

• You have complex pricing models (marketplace, usage-based at scale)
• You need custom payment flows (offline payments, net terms)
• You're processing $10M+ ARR and need to reduce processing costs
• You have dedicated finance/engineering resources