Subscription billing rebuild

The problem

A SaaS startup had grown past their original, hand-rolled Stripe integration. Webhooks were dropped silently, plan changes left customers in inconsistent states, and finance couldn't trust the numbers. They needed it fixed without a risky big-bang migration that might disrupt paying customers.

(Client anonymized — focus is on what was shipped and its impact.)

What I built

• A reliable webhook pipeline — idempotent handlers with persisted event logs, so a missed or replayed Stripe event could no longer corrupt subscription state.
• A single source of truth — reconciled Stripe and the application database so the two could never silently diverge, with a job to catch drift if they ever did.
• Correct plan transitions — upgrades, downgrades, proration, cancellations, and dunning handled explicitly and covered by tests, instead of inferred from whatever Stripe last sent.
• A safe rollout — migrated active subscriptions incrementally behind a flag, with a verified path back at each step.

Outcome

Billing stopped being a source of support tickets and finance surprises. Plan changes became boring — which is exactly what you want from billing. The migration completed with no interruption to active subscriptions, and the team got a runbook for the parts that still needed a human.

What I took from it

• Idempotency and an event log aren't optional for webhooks; they're the whole game.
• A reconciliation job you hope never fires is cheap insurance against the bug you haven't found yet.