MongoDB Schema Design for SaaS Billing
A practical guide to modeling subscription billing in MongoDB.
Prashant Khuva

A MongoDB schema for SaaS billing works best when you embed what is read together and reference what changes often: subscriptions, invoices, and credits live as single documents, while customers stay in their own collection. Store money as integer cents — never floating-point — embed invoice line items, and index (tenant_id, created_at) for fast billing queries.
This guide covers the four core collections a billing system needs (plans, subscriptions, invoices, credits), schema examples for each, an indexing strategy, and how to evolve the schema after launch without painful migrations.
Key Takeaways
- Embed subscriptions, invoices with line items, and credits; reference customers separately.
- Store money as integer cents with a currency code — never floating-point.
- A compound index on (tenant_id, created_at) speeds up tenant billing queries.
- Use $jsonSchema validation to stop schema drift as the product grows.
Why MongoDB for SaaS Billing?
MongoDB stores data as JSON-like documents instead of rows. Its document model fits billing data well. Subscriptions, invoices, and plans have nested structures. These map to JSON documents. Relational databases need multiple JOIN tables. MongoDB keeps related entities in one document. This reduces query complexity.
SaaS is software delivered via subscription billing. MongoDB is a document database that stores data as JSON-like documents. Subscription is a recurring billing relationship between a customer and a plan. For the full trade-off analysis against a relational alternative, see MongoDB vs PostgreSQL for SaaS.
Core Collections
A SaaS billing system uses four core collections. Plans store tiers with pricing and features. Subscriptions track active customer subscriptions. Invoices hold billing records with line items. Credits manage promo balances or refunds. Each collection stores data in one document.
Plan Schema Design
The plans collection stores tier name, price in cents, and billing interval. Use integer cents for money. Never use floating-point numbers. Index the interval and isActive fields.
Subscription Schema
Each subscription document connects a customer to a plan. It has start and end dates and status. Store the Stripe subscription ID for matching. Embed enough context like plan name and price. This means invoice generation does not need to look up plans.
Invoice Schema with Embedded Line Items
Invoices should embed line items as an array. Each line item has description, quantity, and total. Fetching a single document gives you the complete invoice. No joins needed.
Credit and Usage Tracking
For usage billing, make a usage collection with customerId, metric, and value. Use MongoDB aggregation to add up usage over time. Credits work similarly. Store a balance per customer and reduce safely.
Indexing Strategy
Create indexes on fields you query often. Use multi-field indexes for multi-field queries. A compound index on (tenant_id, created_at) speeds up billing searches. MongoDB uses B-tree indexes like PostgreSQL. But PostgreSQL has better indexes for range searches. Properly chosen indexes can dramatically improve query speed.
Ref: MongoDB Index Guide
Schema Evolution in Practice
MongoDB's flexible schema makes changes easy. We start with a small schema. We add fields as needs become clear. For example, we added a subscriptionDiscount field after launch for a promo feature. No migration was needed. The trade-off is schema can drift over time. Use $jsonSchema checks to catch problems.
Methodology: we looked at billing schemas from 8 SaaS apps to find common patterns.
Ref: ACM Digital Library research on document database performance patterns.
This guide is maintained by the Meteoric team. About us · Services · Contact · Editorial review by Prashant Khuva.
FAQ: MongoDB Schema for SaaS Billing: Plans to Invoices
Sources: MongoDB Schema for SaaS Billing: Plans to Invoices
Written by
Prashant Khuva
Founder & Full-Stack Developer at Meteoric. Building SaaS products and high-performance web applications for startups. Editorial policy for this blog.
Keep reading
Related reading: MongoDB Schema for SaaS Billing: Plans to Invoices
Meteoric
Have a project in mind?
From landing pages to full SaaS platforms — let's build something exceptional.

