Skip to content
Meteoric — software development agency
Meteoric — software development agency
MongoDBSaaS

MongoDB Schema Design for SaaS Billing

A practical guide to modeling subscription billing in MongoDB.

PK

Prashant Khuva

Updated 3 min read
MongoDB Schema Design for SaaS Billing

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.
01

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.

02

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.

03

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.

04

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.

05

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.

06

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.

07

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

08

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

Embed when data is read together (invoices with line items) and rarely changes independently. Reference when data changes frequently or is shared across many documents (customer info referenced from invoices). For billing, invoices with embedded line items is the standard pattern.

Store all monetary values as integer cents with an ISO currency code field alongside. Convert to display amounts in your application layer. Avoid storing different currencies in the same field — keep amount and currency as a paired unit.

Store the start and end dates of each billing period directly on the invoice document. For active subscriptions, maintain a currentPeriodStart and currentPeriodEnd that update on renewal. This makes period-based queries trivially simple.

Storing money as floating-point numbers. Floating-point arithmetic introduces rounding errors that compound across thousands of transactions. Store amounts as integer cents with a separate ISO currency code, and do all currency math in integers until display time.

Move when billing logic grows heavy on relational guarantees: multi-table joins across accounts and ledgers, strict transactional consistency, or reporting queries that span many entities. For most early-stage SaaS billing, embedded MongoDB documents are simpler and fast enough.

Use a multi-document transaction when a payment must update several documents together, such as an invoice, a subscription, and a credit balance. Keep single-document updates where possible by embedding line items in the invoice, and make payment handlers idempotent so retried webhooks never double-charge.

PK

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.

Meteoric

Have a project in mind?

From landing pages to full SaaS platforms — let's build something exceptional.