# Multi-Tenant Billing Architecture: Design Patterns for SaaS > Design patterns for building multi-tenant billing systems in SaaS. Covers tenant isolation, metering, event-driven billing, and when to build vs buy billing infrastructure. - **Author**: Ayush Agarwal - **Published**: 2026-04-15 - **Category**: Architecture, SaaS Billing - **URL**: https://dodopayments.com/blogs/multi-tenant-billing-architecture --- Multi-tenant SaaS applications share infrastructure across customers while isolating their data, configuration, and billing. The billing layer is where multi-tenancy gets tricky: each tenant might be on a different plan, in a different currency, with different usage patterns, different billing cycles, and different tax jurisdictions. Building billing for a single-tenant application is straightforward. Building billing that scales across thousands of tenants with different pricing models, payment methods, and compliance requirements is an architectural challenge that has derailed many SaaS companies. This guide covers the design patterns for multi-tenant billing, the decisions you need to make early, and when building your own system makes sense versus using existing infrastructure. ## Core Billing Architecture Components ```mermaid flowchart TD A[Product Catalog] -->|"Plans, pricing, features"| B[Subscription Engine] B -->|"Tenant assignment"| C[Tenant Billing State] D[Usage Metering] -->|"Events"| E[Usage Aggregation] E -->|"Billable amounts"| F[Invoice Generation] C -->|"Plan + usage"| F F -->|"Charge"| G[Payment Processing] G -->|"Result"| H[Revenue Recognition] G -->|"Webhook"| I[Entitlement Service] I -->|"Feature access"| J[Application Layer] ``` ### Product Catalog The product catalog defines what you sell: plans, tiers, add-ons, features, and their prices. In a multi-tenant system, the catalog must support: - Multiple [pricing models](https://dodopayments.com/blogs/subscription-pricing-models): flat-rate, [tiered](https://dodopayments.com/blogs/tiered-pricing-model-guide), [per-seat](https://dodopayments.com/blogs/pay-per-seat-billing-b2b), [usage-based](https://dodopayments.com/blogs/usage-based-billing-saas) - Currency-specific pricing for [multi-currency](https://dodopayments.com/blogs/multi-currency-pricing-global-saas) support - Plan versioning (grandfather existing tenants on old pricing) - Feature flags tied to plan entitlements ### Subscription Engine Manages the lifecycle of each tenant's subscription: creation, upgrades, downgrades, cancellations, pauses, and renewals. Key challenges: - **Proration**: When a tenant changes plans mid-cycle, calculate credits and charges accurately - **Trial management**: Track trial periods, convert to paid, handle expired trials - **Billing cycle alignment**: Some tenants on monthly, others on [annual](https://dodopayments.com/blogs/annual-vs-monthly-billing-saas) - **Grace periods**: How long to maintain access after a failed payment before [involuntary churn](https://dodopayments.com/blogs/involuntary-churn-failed-payments) ### Usage Metering For [usage-based billing](https://docs.dodopayments.com/features/usage-based-billing/introduction), you need to track what each tenant consumes. This requires: - **Event ingestion**: Accept usage events at high throughput from your application - **Tenant isolation**: Each event must be attributed to the correct tenant - **Aggregation**: Roll up raw events into billable quantities (API calls, storage GB, compute hours) - **Idempotency**: Ensure duplicate events do not result in double-billing ```javascript // Example: Ingesting a usage event with Dodo Payments const result = await client.usageEvents.ingest({ events: [ { event_id: `api_call_${Date.now()}`, customer_id: "tenant_abc123", event_name: "api_call", timestamp: new Date().toISOString(), metadata: { endpoint: "/v1/generate", tokens_used: 1500, }, }, ], }); ``` ### Invoice Generation At the end of each billing cycle, the system must: 1. Retrieve the tenant's plan and current pricing 2. Calculate fixed charges (subscription fee) 3. Calculate variable charges (usage, overages) 4. Apply discounts, credits, and [proration](https://dodopayments.com/blogs/billing-credits-pricing-cashflow) 5. Calculate taxes based on tenant location 6. Generate an invoice with line items 7. Initiate payment collection ### Entitlement Service The entitlement service gates feature access based on the tenant's plan. When a tenant upgrades, their entitlements update immediately. When a payment fails, entitlements degrade gracefully. ```javascript // Check if tenant has access to a feature async function hasFeature(tenantId, featureName) { const subscription = await getSubscription(tenantId); const plan = await getPlan(subscription.planId); return plan.features.includes(featureName); } ``` ## Design Patterns ### Pattern 1: Centralized Billing Service All billing logic lives in a single service that all application services call. **Pros**: Single source of truth, consistent billing rules, easier to maintain **Cons**: Single point of failure, can become a bottleneck at scale **Best for**: Most SaaS companies up to ~10K tenants. ### Pattern 2: Event-Driven Billing Application services emit events (user signed up, API called, storage used). The billing service consumes events and processes them asynchronously. ```mermaid flowchart LR A[App Service] -->|"usage.recorded"| B[Event Bus] C[Auth Service] -->|"user.added"| B B -->|"Consume"| D[Billing Service] D -->|"Process"| E[Invoice + Charge] D -->|"Emit"| F["payment.succeeded"] F --> G[Entitlement Service] ``` **Pros**: Decoupled, scalable, resilient to spikes **Cons**: Eventually consistent (slight delay between action and billing), more complex to debug **Best for**: SaaS companies with usage-based components and high event volumes. ### Pattern 3: Billing as External Service Delegate billing entirely to an external platform via [API](https://docs.dodopayments.com/api-reference/introduction). **Pros**: No billing code to maintain, compliance handled, [dunning](https://dodopayments.com/blogs/dunning-management) and [revenue recovery](https://dodopayments.com/blogs/revenue-recovery-saas) included **Cons**: Less customization, dependency on external provider **Best for**: Teams that want to focus on product, not billing infrastructure. [Dodo Payments](https://dodopayments.com) provides this as a [merchant of record](https://dodopayments.com/blogs/what-is-a-merchant-of-record), handling subscriptions, usage-based billing, invoicing, tax, and payments through a single API. ## Tenant Isolation in Billing Billing data isolation is critical. A bug that charges Tenant A for Tenant B's usage is a trust-destroying event. ### Data Isolation Strategies - **Row-level isolation**: All tenants in the same database tables, filtered by `tenant_id`. Simple but requires discipline to never forget the filter. - **Schema-level isolation**: Each tenant gets their own database schema. Better isolation but harder to query across tenants. - **Database-level isolation**: Each tenant gets their own database. Maximum isolation, highest operational overhead. For billing specifically, row-level isolation with strict `tenant_id` enforcement is the most common pattern. Add database constraints to prevent cross-tenant data leaks: ```sql -- Every billing table includes tenant_id with a NOT NULL constraint CREATE TABLE invoices ( id UUID PRIMARY KEY, tenant_id UUID NOT NULL REFERENCES tenants(id), amount_cents BIGINT NOT NULL, currency VARCHAR(3) NOT NULL, status VARCHAR(20) NOT NULL, created_at TIMESTAMP NOT NULL DEFAULT NOW() ); -- Enable row-level security on the table ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; -- Row-level security policy CREATE POLICY tenant_isolation ON invoices USING (tenant_id = current_setting('app.tenant_id')::UUID); ``` ## Build vs Buy Decision | Factor | Build Your Own | Use External (Dodo, etc.) | | ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------- | | Time to market | 3-6 months | 1-2 weeks | | Maintenance | Ongoing engineering cost | Provider handles it | | Customization | Unlimited | API-limited | | Tax compliance | You handle | [Included](https://dodopayments.com/blogs/global-vat-gst-ai-saas) | | PCI compliance | [You handle](https://dodopayments.com/blogs/pci-compliance-checklist-saas) | Included | | Dunning/recovery | You build | Included | | Cost at scale | Lower marginal cost | Higher per-transaction cost | | Engineering focus | Diverted to billing | Focused on product | > The most expensive billing system is the one you build yourself before product-market fit. You will rebuild it at least twice as your pricing model evolves. Use an external billing API until you are processing enough volume that the per-transaction cost justifies the engineering investment of building your own. > > - Ayush Agarwal, Co-founder & CPTO at Dodo Payments ### When to Build - Processing $10M+ annually and billing is a core differentiator - Highly custom pricing models that no external provider supports - Regulatory requirements that mandate in-house data processing ### When to Buy - Pre-product-market-fit (pricing will change) - Team under 20 engineers (cannot afford billing team) - Selling globally (tax compliance alone justifies external provider) - [Usage-based billing](https://dodopayments.com/blogs/implement-usage-based-billing) with complex metering (solved problem, do not reinvent) For implementation guidance, see our guides on [building a billing system for AI SaaS](https://dodopayments.com/blogs/build-billing-system-ai-saas), [billing infrastructure](https://dodopayments.com/blogs/billing-infrastructure-age-ai-agents), [best billing APIs](https://dodopayments.com/blogs/best-billing-apis-developers), and [payments architecture](https://dodopayments.com/blogs/payments-architecture-saas). ## FAQ ### What is the hardest part of multi-tenant billing? Proration and plan changes. Calculating the correct charge when a tenant upgrades from a $49/month plan to a $99/month plan on day 15 of their billing cycle, with a prorated credit for the remaining $49 period and a prorated charge for the $99 period, across different currencies and tax jurisdictions, is surprisingly complex. Most billing bugs live in proration logic. ### How do I handle different pricing for different tenants? Use plan versioning and custom pricing overrides. Maintain a product catalog with standard plans, but allow per-tenant price overrides for enterprise deals or negotiated rates. Store the override in the tenant's billing configuration, not by modifying the catalog. ### Should I use a message queue for billing events? Yes, for usage-based billing. A message queue (Kafka, SQS, RabbitMQ) between your application and billing service ensures events are not lost during spikes, provides replay capability for debugging, and decouples your application from billing processing latency. ### How do I test multi-tenant billing? Create automated tests that simulate multiple tenants with different plans, currencies, and usage patterns executing billing operations simultaneously. Test edge cases: plan changes mid-cycle, failed payments, currency conversions, and concurrent usage events for the same tenant. Use your payment provider's sandbox for end-to-end testing. ### When should I migrate from an external billing service to in-house? Consider migration when billing costs exceed 1-2% of revenue AND you have engineering resources to build and maintain billing infrastructure (typically 2-3 dedicated engineers). For most SaaS companies under $20M ARR, external billing is more cost-effective than the engineering investment of building your own. ## Final Thoughts Multi-tenant billing is a solved problem at the infrastructure level. Unless billing is your core product, use existing platforms and focus your engineering on what differentiates your business. For multi-tenant billing infrastructure that handles subscriptions, usage metering, tax compliance, and global payments, visit [Dodo Payments](https://dodopayments.com) and check the [pricing](https://dodopayments.com/pricing). --- - [More Architecture articles](https://dodopayments.com/blogs/category/architecture) - [All articles](https://dodopayments.com/blogs)