Building an Idempotent Stripe Billing Enforcement Engine for Firestore

When you're building subscription billing with Stripe webhooks, you quickly discover a harsh reality: webhooks can arrive delayed, duplicated, or out of order. For a youth sports stats SaaS platform I'm building, this created a critical problem—plan and status updates were scattered across multiple handlers with no guarantee of consistency. This is the story of building a unified plan enforcement engine that solved webhook chaos, eliminated duplicate logic, and added automatic drift correction—all while maintaining a complete audit trail. The Problem: Webhook Drift and Duplicate Logic What We Started With Our billing system had plan/status update logic in four separate locations: Stripe webhook handler (/api/billing/webhook/route.ts) - 5 event handlers Event replay endpoint (/api/admin/billing/replay-events/route.ts) - 5 replay handlers Billing auditor (src/lib/stripe/auditor.ts) - drift detection Manual admin operations - future admin dashboard actions Each location had its own versio