Overview
The Payment & Subscription Billing Engine is a comprehensive billing system designed for SaaS applications that need to handle the full complexity of recurring revenue: subscription plans, usage-based pricing, plan changes with proration, automated invoicing, failed payment recovery, and tax calculation. It wraps Stripe's APIs into a well-structured, opinionated codebase that handles the dozens of edge cases that make billing systems notoriously difficult to get right.
Built with Node.js, TypeScript, PostgreSQL, and Redis, this engine maintains a local billing state that stays synchronized with Stripe through a robust webhook processing layer. Your application code interacts with clean, type-safe service methods rather than directly calling Stripe APIs, giving you a consistent abstraction that handles retry logic, idempotency, and error recovery.
Architecture
The billing engine is structured into five core modules:
- Customer Management -- Maps your application users to Stripe customers, handling creation, updates, and payment method management. Supports multiple payment methods per customer with a designated default. The module handles the Stripe Customer Portal integration, letting users manage their own payment details and billing history.
- Plan & Pricing Engine -- A flexible pricing model supports flat-rate plans, per-seat pricing, tiered pricing, and usage-based metering. Plans are defined in a configuration file and synced to Stripe Products and Prices on deployment. Feature entitlements are attached to plans, enabling feature gating at the application layer.
- Subscription Lifecycle -- Manages the complete subscription lifecycle: creation, trial periods, activation, plan changes (upgrade/downgrade) with automatic proration, pausing, resumption, and cancellation (immediate or end-of-period). Each state transition is recorded in a local event log for audit and debugging.
- Invoice & Revenue Tracking -- Invoices are generated automatically by Stripe and synced to your local database. The engine tracks MRR (Monthly Recurring Revenue), churn, and expansion revenue. Usage-based charges are reported via a metering API and included in the next invoice cycle.
- Dunning & Recovery -- When a payment fails, the dunning workflow initiates a configurable retry sequence with escalating email notifications. The system tracks payment failure reasons, supports updating payment methods mid-dunning, and can automatically pause or cancel subscriptions after exhausting retry attempts.
Key Features
- Subscription Management -- Full lifecycle support: create, trial, activate, upgrade, downgrade, pause, resume, cancel. All with proper proration and no billing surprises.
- Usage-Based Billing -- Report usage events via API, and they are automatically aggregated and included in the next invoice. Supports sum, max, and last-during-period aggregation strategies.
- Proration -- Plan changes mid-cycle are prorated automatically. Supports immediate proration, proration at next billing cycle, and no proration modes.
- Dunning Workflows -- Automated payment recovery with configurable retry schedules, escalating email notifications, and grace periods before service degradation.
- Invoice Generation -- Automated invoice creation with line items, tax calculation, and PDF rendering. Invoices are stored locally and accessible via API.
- Feature Gating -- Middleware that checks plan entitlements before allowing access to features. Returns appropriate upgrade prompts when limits are reached.
- Webhook Resilience -- Stripe webhook processing with signature verification, idempotent handling, and dead-letter queue for failed events.
- Revenue Analytics -- Track MRR, ARR, churn rate, expansion revenue, and average revenue per user. Exportable data for financial reporting.
What's Included
- Full TypeScript source code with strict type safety
- Stripe integration layer with all webhook handlers
- Subscription service with full lifecycle management
- Usage metering API and aggregation engine
- Dunning workflow with email templates (React Email)
- Invoice sync and PDF generation
- Revenue analytics queries and dashboard data endpoints
- Database schema and migrations (Prisma)
- Comprehensive test suite with Stripe mock server
- Deployment guide and environment configuration reference
Who Is This For?
This engine is for SaaS teams that are ready to move beyond basic Stripe Checkout and need a proper billing system. If you are building a product with multiple pricing tiers, usage-based components, team billing, or enterprise plans, this gives you the infrastructure that handles the edge cases: proration when users switch plans mid-cycle, dunning when cards expire, usage aggregation across billing periods, and accurate MRR tracking.
It is built for teams that want to own their billing logic rather than depending on a third-party billing platform. You get full source code, full control, and full visibility into how every billing operation works.