Should a SaaS startup use Stripe Billing, a purpose-built billing platform, or build custom billing?

The build-vs-buy decision for billing depends on the revenue model complexity and the anticipated pricing iteration frequency, not the team size alone. Stripe Billing is well-suited to flat subscriptions, seat-based pricing, and simple usage-based billing where the metered quantity maps directly to a Stripe Meter object. It is poorly suited to complex usage aggregations (multi-dimensional metering, prepaid credit drawdown with rollover, tiered usage with committed minimums), contractual pricing with custom line items, or multi-currency invoicing with entity-level tax configuration. Purpose-built billing platforms (Orb, Metronome, Lago, Chargebee) add a metering and pricing abstraction layer that decouples the revenue model from the payment processor API; the trade-off is a vendor dependency, an additional integration surface, and a recurring cost that becomes significant before Series B. Custom billing — building subscription management, invoicing, dunning, and payment retries from scratch — is almost never the right choice at seed or Series A because the ongoing maintenance cost (Stripe API changes, dunning logic, tax compliance updates, SCA regulations) exceeds the engineering cost of any alternative. The billing architecture decision record should document which approach was chosen and why, what the revenue model ceiling of the chosen approach is, and what the trigger for re-evaluation is — otherwise the team discovers the ceiling when the product team has already promised a pricing change to a major customer.

What is the correct way to implement usage-based billing metering in a SaaS product?

Usage-based billing metering requires three components that are often conflated in early implementations: event ingestion (capturing usage events from the application with sufficient metadata to aggregate them correctly), aggregation (summing, counting, or otherwise reducing events into billable quantities for a given billing period and customer), and rating (applying the price schedule to the aggregated quantity to produce a line item on an invoice). These three components have different requirements and should be designed as separate concerns. Event ingestion must be reliable (events cannot be dropped without billing discrepancy), ordered (events must be attributable to the correct billing period), and attributable (each event must carry a customer or workspace identifier and sufficient context to be audited). Aggregation must be idempotent (reprocessing the same event twice should not double-count the usage), queryable (the aggregated usage must be readable by customers from within the product before the invoice is generated), and auditable (the aggregation query must be reproducible to answer the customer question 'why does my invoice say I used 1.4 million API calls in March?'). Rating must be versioned (price schedule changes must not retroactively change invoice amounts for events that occurred under the prior schedule), contract-aware (committed minimums, volume discounts, and prepaid credits must be applied in the correct order), and reconcilable (the rated amount on the invoice must be traceable to specific events in the event store). Implementing all three correctly in an ad-hoc, per-feature manner is how billing systems accumulate technical debt that makes pricing changes expensive.

How does the billing architecture affect revenue recognition under ASC 606?

ASC 606 requires recognizing revenue when (and to the extent that) performance obligations are satisfied, not when cash is collected. For SaaS, this means subscription revenue is recognized ratably over the subscription period, usage-based revenue is recognized when the usage occurs (when the API call is made, the document is processed, the seat is occupied), and setup fees and professional services revenue follows the contract's performance obligation structure. The billing architecture affects revenue recognition in three ways: (1) Period attribution — usage events must be timestamped in a way that allows correct period attribution; if the billing system aggregates usage monthly and invoices at the end of the month, but accounting periods close mid-month, the system must be able to produce accrual-basis revenue figures for arbitrary period cuts, not just invoice dates; (2) Deferred revenue — prepaid subscriptions, prepaid credits, and annual-plan-monthly-pay contracts all create deferred revenue liabilities that must be tracked at a line-item level and reduced as performance obligations are satisfied; if the billing system only records cash collected and invoice issued, not the period the revenue belongs to, the deferred revenue schedule must be reconstructed from invoice data at audit time, which is error-prone; (3) Contract modifications — when a customer upgrades mid-period, downgrades, or cancels, ASC 606 requires specific accounting treatment for the remaining performance obligation; if the billing system handles plan changes by creating new subscriptions and crediting the old one without preserving the original contract terms in an auditable form, the revenue recognition entries for the modification cannot be produced without reconstructing the history from change logs. Document the revenue recognition model in the billing architecture decision record — which events create revenue, how deferred revenue is tracked, and how contract modifications are handled — so that the audit trail exists by design rather than by reconstruction.

What is the payment processor portability cost and when does it matter?

Payment processor portability cost is the engineering and business cost of migrating customers from one payment processor to another. It matters in three scenarios: when a major customer requires a payment method the current processor does not support (ACH pull, SEPA Direct Debit, wire transfer-triggered invoices, procurement system integration), when the processor's pricing or terms change in a way that makes migration worthwhile at scale, and when a compliance requirement (PCI scope reduction, data residency, processor-level SLA) cannot be met by the current processor. The migration cost has three components: (1) card migration — stored card data (PANs, expiry dates, CVV2) cannot be transferred between processors without a card scheme-level migration process, which requires involvement from Visa and Mastercard, the source processor, the destination processor, and your card vault; the process takes 3–6 months and has a typical success rate of 60–80% because some cards expire or are replaced during the migration window; (2) subscription migration — active subscriptions must be recreated in the destination processor with the correct billing dates, amounts, and trial periods; this requires a cutover period during which the source processor handles renewals for migrating subscribers while the destination handles new subscribers; (3) integration migration — if the payment processor API is called directly in multiple services rather than through a billing abstraction layer, every callsite must be updated; the migration scope is proportional to the number of integration points, not the number of customers. Document the expected integration surface in the billing architecture decision record — how many services call the processor API directly, what the abstraction boundary is, and what the migration trigger would be — so that a migration is a planned event rather than an emergency response.

The SaaS billing architecture decision record: why the billing model you chose determines your revenue recognition complexity and your pricing iteration speed

July 9, 2026 · WhyChose

The SaaS billing architecture decision is made during the first paid-plan sprint, almost always under time pressure from a self-imposed pricing deadline or an investor milestone. The team evaluates Stripe Billing, decides that a flat monthly subscription is sufficient for launch, and ships a checkout flow in a week. The decision is not written down because it feels like an implementation detail — a few Stripe API calls, a webhook handler, and a subscription table — not a structural choice with consequences that compound for three years. What is not written down is the metering strategy that will be needed the first time a customer asks "how many API calls did I make this month?", the tax handling approach that will become complicated when the company expands to Europe, the payment method surface that will matter when the first enterprise customer requires purchase-order-based invoicing, and the pricing iteration mechanism that will determine how long it takes to ship the usage-based tier the product team has been promising since the last quarterly planning.

The billing architecture decision record does not exist because billing feels like infrastructure that can be improved incrementally. What happens instead is that the billing system accumulates features added on top of the original flat-subscription model: a seat count added as a Stripe quantity multiplier, a usage charge added as a Stripe metered subscription item, a free-tier credit added as a Stripe coupon, a partner discount added as a Stripe promotion code, a volume discount negotiated with a major customer added as a manually-adjusted invoice. Each addition is reasonable in isolation. The cumulative result is a billing system in which the answer to "what will a customer pay this month?" requires querying four different Stripe objects, checking two database tables maintained outside Stripe, and applying business logic that exists only in a billing service written eighteen months earlier by an engineer who has since left. The pricing team cannot launch a new plan without two weeks of engineering work to model the plan in the current system. The finance team cannot close the month without a four-hour manual reconciliation between Stripe's billing data and the general ledger. The revenue recognition schedule for the annual audit requires three days of SQL queries that the engineering team runs once a year and has never tested for correctness.

Two things that happen when the decision is not written down

The usage-based tier that required rebuilding the metering system

A 60-person B2B SaaS company had been operating on a flat subscription model for three years: three tiers at $49, $199, and $499 per month, differentiated by user seat count and a set of feature flags. Billing was simple — a Stripe subscription for each customer, a webhook handler that updated a subscription_status table when payments succeeded or failed, and a Stripe customer portal for self-serve plan changes. The billing decision had been made by the founding CTO in the first week of monetization: "use Stripe, flat subscriptions, revisit when we need more." The "revisit when we need more" condition was never written down as a trigger — no criteria, no timeline, no designated owner.

The product team's annual roadmap included a usage-based add-on tier: customers would pay $0.004 per document processed, with a $99 monthly minimum. The pricing model had been validated with five enterprise customers who had confirmed they preferred consumption-based pricing for the document processing feature over a flat seat license. The engineering estimate for the billing change was one sprint — two weeks. The actual elapsed time from kickoff to billing live in production was four months.

The first week of the sprint revealed that the application had no metering infrastructure. Document processing events were logged to the application log but not counted or attributed to customers in any queryable store. The billing engineer could not answer "how many documents did customer X process in the last 30 days?" without writing a custom log aggregation query against the logging infrastructure, which had never been used for billing attribution and had a retention window of 45 days — shorter than the 90-day lookback the enterprise customers had asked for in contract negotiations. The log format had changed six months earlier when the engineering team switched from unstructured logging to structured JSON, and the document processing event schema change had not been backward-compatible: the customer identifier field had been renamed from user_id to workspace_id in the new schema, meaning that accurate usage attribution required a mapping table between the two identifier spaces that had to be reconstructed from the user management database.

The second problem surfaced in week three. Stripe's metered billing at the time of implementation used a model in which the application submitted usage records to Stripe's API during the billing period and Stripe aggregated them into the invoice at period end. This model required the application to push usage events to Stripe in near-real-time — a push-based architecture that meant Stripe held the authoritative usage record. The engineering team discovered that they could not show customers their current usage from within the product without calling the Stripe API to retrieve the pending usage total, which was rate-limited and did not return the granular event log needed to answer "which documents contributed to this month's usage?" The in-product usage dashboard the product team had promised to enterprise customers as part of the deal — a real-time view showing which document batches had consumed what usage, broken down by date and document type — was not satisfiable by Stripe's metered billing API.

The team redesigned the metering system from scratch: a dedicated events table with idempotency keys and workspace attribution, a nightly aggregation job that summed usage by workspace and billing period, a Stripe usage record submission that synchronized the aggregated totals to Stripe at the end of each billing period rather than in real-time (which eliminated the rate-limit problem), and a usage API endpoint that returned the event-level breakdown from the internal events table rather than from Stripe. The in-product dashboard pulled from the usage API. The Stripe invoice total came from the aggregated totals. Reconciliation between the two — the assertion that the sum of event-level records matched the Stripe invoice total — was implemented as a nightly check that paged on discrepancy.

The migration from log-based event attribution to the new events table required backfilling three months of historical usage from the application logs, with a manual correction pass for the period when the identifier field rename had created attribution gaps. The four-month elapsed time broke down as follows: one month to design the new metering system and backfill historical data, one month to implement the events table, aggregation job, usage API, and Stripe synchronization, one month to implement and validate the in-product usage dashboard against the five enterprise customers' actual usage patterns, and one month of parallel-run testing in which both the old log-based system and the new metering system ran simultaneously and their outputs were compared daily before the old system was decommissioned. The original decision — that flat subscriptions were sufficient for launch and metering would be added when needed — had not included any assessment of what "adding metering" would require. If the decision had been written down with the explicit note that "usage-based billing will require a dedicated events table with customer attribution — this design does not exist today and will require a sprint to build when needed," the product team's original two-week estimate would have been immediately corrected during planning rather than discovered in week one of the sprint.

The payment processor integration that blocked the enterprise deal

A 25-person developer tools startup had chosen Stripe for payment processing at founding, with Stripe API calls made directly from seven different services: an API gateway service that charged for API key issuance, a workspace service that managed subscription plans, a team service that handled seat billing, a billing portal service that surfaced plan management to end users, an admin service that allowed support staff to apply credits and issue refunds, a webhook service that processed Stripe events, and a reporting service that queried Stripe's data export API for finance dashboards. The direct integration pattern had been chosen because it was the fastest way to ship each individual billing feature — adding a new billing action meant adding a Stripe API call to the service that needed it. There was no billing abstraction layer and no billing service that owned the payment processor integration centrally.

Eighteen months in, the startup's sales team closed a term sheet with a Fortune 500 enterprise customer representing $280,000 in annual contract value. The legal team's procurement process required payment via purchase order and net-30 invoice terms — wire transfer payment against an invoice generated by the seller and submitted to the customer's accounts payable system. Stripe Billing supports invoice-based payment (Stripe Invoicing with ACH bank transfer or check payment), but the implementation required changes to how the workspace service modeled the customer's subscription: instead of a Stripe Subscription object that charged the customer's card automatically at period end, the enterprise customer needed a Stripe Invoice object generated monthly, emailed to their accounts payable contact, and marked as paid when the wire transfer cleared rather than when a card was charged. The webhook handling for payment confirmation was completely different between the two models.

The team scoped the change at one week. The actual elapsed time was six weeks, and the scope expansion traced directly to the direct integration pattern. The workspace service needed to handle the new invoice-based payment flow, but the billing-related logic — subscription creation, plan change handling, payment method management, dunning sequences — was distributed across all seven services rather than centralized in a billing abstraction. Making the enterprise customer's payment model work correctly required changes to the workspace service, the webhook service, the admin service (which issued refunds differently for invoice-based payments), and the billing portal service (which needed to show the invoice status rather than the card charge status to enterprise users). The reporting service's finance dashboards pulled MRR figures from Stripe's Subscription data model; for the enterprise customer, MRR was booked at invoice generation rather than at invoice payment, which required a new aggregation path that the reporting service had not been designed to handle.

Four engineers spent six weeks auditing every Stripe API call across the seven services, mapping the data flow for both the card-based and invoice-based payment models, designing a billing abstraction layer that both models could satisfy, migrating the existing Stripe calls behind the abstraction, and implementing the invoice-based payment model using the new abstraction. The result was a billing service that owned all Stripe API interactions, exposed a billing domain model (create_subscription, change_plan, issue_credit, generate_invoice, record_payment) that other services called, and translated those domain operations into the appropriate Stripe API calls for the customer's payment model. The enterprise deal closed five weeks after the billing service went live, six weeks after the original signature deadline — the customer had waited, but the delay had required two additional negotiation calls and a contract extension to the offer validity period.

Both outcomes share the same structural cause. The first company's flat subscription billing was not wrong at launch — it was the right decision for a product that had not yet validated the usage-based pricing model with paying customers. The second company's direct Stripe integration pattern was not wrong for the first twelve services that needed billing functionality — it was the fastest way to ship. What was missing in both cases was the billing architecture decision record: the explicit documentation of what the chosen approach covered and what it did not, the metering data model that would be needed if usage-based billing was added, the payment model abstraction that would be needed if payment methods beyond card-on-file were required, and the trigger criteria that would prompt a billing architecture review before a customer requirement or a pricing sprint discovered the gap under deadline pressure.

Three structural properties that are set at billing architecture selection time

The revenue model ceiling and its metering data requirements

Every billing architecture has a revenue model ceiling: the set of pricing models it can implement without an architecture change. A flat subscription system's ceiling is the first pricing model that requires per-customer usage measurement. A seat-based subscription system's ceiling is the first pricing model that requires non-seat consumption metering. A Stripe-native metered billing implementation's ceiling is the first pricing model that requires usage granularity, aggregation logic, or attribution rules that Stripe's metering API cannot express — typically multi-dimensional usage (charging by both API calls and data volume on a combined rate schedule), prepaid credit drawdown with rollover, or usage commitments with true-up at period end.

The ceiling is not inherently a problem — every system has a ceiling, and the right ceiling for a seed-stage product is probably lower than the ceiling for a Series B product. The problem is not documenting the ceiling at decision time, so the team discovers it when the product roadmap has already committed to a pricing model that exceeds it. Document the ceiling explicitly: "this billing architecture supports flat subscriptions and seat-count-based pricing; usage-based pricing requires adding a metering events table with the schema documented in the appendix." The ceiling statement gives the product team the information they need to sequence pricing decisions correctly and gives engineering the warning they need to start metering infrastructure before the pricing sprint begins.

The metering data requirements are the technical complement to the revenue model ceiling. Metering data has three properties that must be designed before the first usage event is recorded: attribution (which field identifies the billable entity — customer, workspace, organization, or seat — and how that identifier maps to the billing system's customer record), idempotency (how duplicate event submissions are detected and deduplicated, to prevent double-counting from retries), and period boundaries (how the billing period cutoff is handled for events that arrive late — an API call made at 11:59 PM on the last day of the month whose log record arrives at 12:03 AM belongs to which billing period?). Getting attribution wrong causes billing disputes. Getting idempotency wrong causes overcharges. Getting period boundaries wrong causes revenue recognition errors. All three must be decided before the first usage event is stored, not reconstructed from logs after the metering system is already in production. Document them in the billing architecture decision record.

The relationship between metering data and the data retention decision record is particularly important: usage event records are both operational data (needed to generate invoices) and audit data (needed to answer customer disputes and tax authority questions). The retention policy for billing event data is typically longer than the retention policy for application logs, and the two are frequently confused in early implementations where usage events are stored in the application log rather than in a dedicated billing events store. If the billing events are stored only in the application log and the log retention policy is 45 days, the team will not discover the gap until they are twelve months in and a customer asks for a usage breakdown covering a period beyond the retention window.

The payment processor coupling and the vendor transition cost

The payment processor is chosen once and replaced rarely. Stripe's dominance in the developer market means most SaaS companies choose Stripe by default, which is the correct default choice — Stripe's API surface, documentation, and developer experience are best-in-class for most use cases. The billing architecture decision is not whether to use Stripe; it is how tightly to couple the rest of the system to Stripe's specific API design.

Direct processor coupling — calling the Stripe API directly from application services — means that every Stripe-specific data model (Subscription, Invoice, PaymentIntent, Customer, Price, Product, Meter) becomes part of the application's domain model. The billing logic is expressed in Stripe API terms rather than in business domain terms. When a plan change is handled by calling stripe.subscriptions.update() with a specific set of parameters, the plan change logic encodes Stripe's subscription model — proration behavior, billing cycle anchoring, trial period handling — rather than the business's desired pricing behavior. When the business needs pricing behavior that Stripe's subscription model does not directly support, the gap is filled with workarounds (scheduled subscriptions, manual invoices, webhook-driven state machines) that become invisible technical debt because they are distributed across services rather than centralized in a billing domain.

A billing abstraction layer — a billing service that owns all processor interactions and exposes a business-domain billing API to other services — has a higher initial implementation cost (one to two weeks to design and build versus adding Stripe calls directly) and pays off when: (a) the business needs a pricing model that requires switching from one Stripe API object type to another (subscriptions to invoices, metered subscriptions to usage records), (b) a major customer requires a payment method or payment flow that the direct integration pattern does not accommodate cleanly (purchase-order invoicing, ACH debit with bank verification, SEPA mandates), or (c) the business evaluates migrating to a purpose-built billing platform and discovers that the migration scope is proportional to the number of Stripe API call sites across the codebase. Document the chosen coupling level — direct integration or abstraction layer — in the billing architecture decision record, with the explicit note of what payment model changes the chosen approach can accommodate without a refactor and what changes would require one.

The payment processor portability cost also interacts with the multi-tenancy decision record: the customer data model in the billing system (how Stripe Customer objects map to the application's account hierarchy — one Stripe Customer per user, per organization, per workspace, per billing entity) determines how complex multi-tenant billing scenarios are handled, including parent-account invoicing (a parent organization pays a single invoice that covers all child workspace subscriptions), reseller billing (a partner is billed for all of their customers' usage under a reseller agreement), and usage rollup (usage from multiple workspaces is aggregated against a single committed spend agreement). If the customer data model was designed for single-tenant billing and the application later adds organizational hierarchy, the billing customer model and the processor customer model may be out of sync — a common source of billing complexity that is cheaper to design correctly at the start than to migrate later.

The pricing iteration mechanism and the change management cost

Pricing is the product team's highest-leverage variable and the billing system's highest-frequency change surface. How quickly the team can ship a pricing change — add a new tier, change a per-unit price, restructure the feature allocation across plans, launch a time-limited discount — is a function of how the billing architecture models prices and how the pricing change propagates through the system.

Three failure modes in pricing iteration deserve documentation at billing architecture selection time. The first is price hardcoding: prices expressed as constants in application code or as literal values in database schemas rather than as references to a pricing configuration store. A hardcoded $49 monthly price means that changing the price requires a code deployment or a database migration, not a configuration change. More importantly, it means that historical prices are not preserved — the system does not know that a customer who signed up on a given date was charged $49 because of a specific pricing policy, not because $49 is the current price. Price hardcoding makes it impossible to answer the question "what price should we bill this customer, given when they signed up and what promotional pricing they accepted?" without reconstructing the pricing history from git blame or deployment records.

The second failure mode is plan proliferation: the accumulation of grandfathered pricing plans that cannot be migrated because the migration cost is higher than the revenue impact of leaving customers on the old plan. Plan proliferation occurs when pricing changes are implemented by creating new Stripe Price objects for new customers while leaving existing customers on the old Price objects, without a documented migration strategy or a sunset date for the old pricing. A billing system with forty active Stripe Price objects — because pricing has been changed twelve times over three years and each change created three new Price objects (one per tier) without retiring the old ones — is a billing system in which no engineer can confidently answer "how many customers are on each pricing plan?" without running a specific query against both Stripe's API and the application database.

The third failure mode is discount accumulation: the use of processor-native discount mechanisms (Stripe Coupons, Stripe Promotion Codes) for what are effectively contract terms (a 20% discount negotiated with a specific enterprise customer for the first year of a multi-year contract). When discounts are managed as Stripe coupons, they are visible in Stripe's dashboard but not in the application's customer record; the renewal logic must check Stripe for applicable coupons at each billing cycle; and the financial reporting must reconcile discounted revenue against list prices using Stripe's data rather than from the application's own contract terms store. When the coupon expires or is incorrectly applied to the wrong customer, the billing error surfaces as a customer support ticket rather than as a system alert. Document the pricing iteration mechanism explicitly: where prices live, how they are versioned, what the process is for retiring old pricing plans, and how contractual discounts are tracked and applied.

The pricing iteration speed is directly correlated with whether the billing architecture was designed with iteration in mind. A billing system where prices are stored in a versioned configuration store, plans are defined as named objects that reference the configuration store, and discount terms are stored in a contracts table that the billing system reads at invoice generation time supports weekly pricing experiments. A billing system where prices are hardcoded, plans are Stripe Price objects, and discounts are Stripe Coupons supports quarterly pricing changes with two weeks of engineering work each. Both architectures can work; the choice determines the team's pricing agility for the life of the product. Document which architecture was chosen and why — the billing architecture decision record that explains "we chose Stripe-native pricing because our pricing model is stable and we expect fewer than four changes per year" is a different record from "we built a pricing configuration service because we expect to run pricing experiments monthly as we find product-market fit."

Five sections the billing architecture decision record should contain

1. Revenue model selection and ceiling documentation

State the initial revenue model (flat subscription, seat-based, usage-based, hybrid) and document its ceiling — the pricing models the current architecture cannot support without an architecture change. Include the metering data requirements for the next model in the sequence: if the current architecture is flat subscriptions, document the events table schema and attribution model that would be needed to add usage-based billing. Document the trigger for re-evaluating the billing architecture: a specific pricing model requirement from the product roadmap, a usage threshold at which the current metering approach becomes operationally expensive, or a customer segment requirement (enterprise customers requiring invoice-based payment, resellers requiring partner billing).

The revenue model documentation should include the tax handling scope: whether the billing architecture handles sales tax collection (Stripe Tax, Avalara, TaxJar, or no automated tax collection), which tax jurisdictions the system is configured for, and what the expansion process is for adding new tax jurisdictions when the company expands geographically. Tax misconfiguration is one of the highest-risk billing errors — overcharging tax creates customer refund obligations, undercharging tax creates company tax liability — and the tax handling approach is almost never documented in the original billing implementation. Include it in the decision record, even if the current answer is "we are not collecting sales tax below the nexus threshold; the trigger for adding automated tax collection is crossing the economic nexus threshold in three or more US states."

2. Payment processor selection and abstraction boundary

Document the chosen payment processor and the rationale, including what alternative processors were evaluated and why they were rejected. For a Stripe selection, the rationale typically includes API quality, documentation, developer experience, supported payment methods, and geographic coverage — but also the implicit acceptance of Stripe's pricing model (2.9% + $0.30 per transaction for card payments, plus the cost of Stripe Billing, Stripe Tax, and Stripe Radar if used).

Document the abstraction boundary: whether payment processor calls are made directly from application services or through a billing abstraction layer. If direct integration, document the set of services that make Stripe API calls and the types of calls each service makes — this is the migration scope if the team later needs to introduce an abstraction layer or change processors. If abstraction layer, document the billing domain API (the business-domain operations the billing service exposes) and how those operations map to the processor's API for the current revenue model. Document the payment method surface: which payment methods are supported (credit card, ACH debit, SEPA, wire transfer, purchase-order invoicing) and the process for adding a new payment method when a customer requires one.

3. Metering infrastructure and usage data model

If the current revenue model includes usage-based pricing, or if the roadmap anticipates adding usage-based pricing within the next eighteen months, document the metering infrastructure: the events table schema (including the customer attribution field, the idempotency key, the event type, the quantity, the timestamp, and any metadata fields needed for breakdown queries), the aggregation job (frequency, period boundary handling, late-arrival policy), the synchronization mechanism to the payment processor (push-based or period-end batch), and the in-product usage reporting API (which fields are exposed, what the latency is between event occurrence and visibility in the usage dashboard).

Include the backfill strategy: how historical usage would be reconstructed if the metering system is introduced after the feature it meters has already shipped. If usage events are currently captured in application logs rather than in a dedicated events table, document the log schema, the log retention policy, and the mapping from log fields to billing attribution fields. This documentation will be essential if the metering system needs to be built after the feature has been live for several months and the historical data needs to be backfilled for accurate billing and revenue recognition. The relationship between metering data design and the database connection pooling decision record matters here: high-volume event ingestion at billing period boundaries can cause connection pool saturation if the aggregation job runs at the same time as peak application traffic.

4. Revenue recognition model and audit trail requirements

Document the revenue recognition model: which events create revenue, how deferred revenue is tracked, and how contract modifications (upgrades, downgrades, cancellations, renewals) are handled in the billing system and in the general ledger. This section should be written in consultation with the finance team or the company's accountant, not unilaterally by engineering — revenue recognition is a financial reporting requirement with audit implications, and the billing system's data model determines whether the revenue recognition schedule can be produced from system data or requires manual reconstruction at each accounting close.

Include the revenue reconciliation process: the specific queries or reports that finance runs to close each month, the frequency of reconciliation between the billing system and the general ledger, and the alert or process for handling billing discrepancies (invoice amounts that do not match the revenue recognition entries). Document the audit trail requirements: how long billing event records must be retained (typically seven years for tax purposes in most jurisdictions), whether the billing system's data is considered the system of record for revenue or a subsidiary ledger, and what the process is for producing billing records in response to a tax authority request or a financial audit. A data governance decision record that does not include billing data retention requirements is incomplete — billing records have different retention requirements and access control requirements than application data.

5. Pricing iteration mechanism and plan lifecycle management

Document where prices live (hardcoded in application code, database table, processor-native Price objects, external pricing configuration service) and how they are versioned. Include the plan lifecycle management process: how new plans are introduced, how existing customers are migrated between plans, how old plans are retired, and what the grandfathering policy is for customers on plans that are no longer sold. Document the discount management model: whether discounts are managed in the payment processor (coupons, promotion codes), in an application-level contracts table, or in a combination of both, and how discounts are applied at invoice generation time.

Include the pricing change authorization process: who can approve a pricing change, what the required lead time is between a pricing decision and a pricing change going live in the billing system, and what the customer notification requirement is for price increases. This process is often informal in early-stage companies and becomes a source of coordination failures when the product team wants to launch a pricing change in the next sprint but engineering needs two sprints to implement it and the legal team needs to review customer communication thirty days before the change takes effect. Documenting the process explicitly — even if the current process is "the CEO decides and the billing engineer implements it in the next sprint" — gives the team the shared understanding needed to plan pricing changes on realistic timelines. The pricing iteration mechanism connects directly to the API versioning decision record when pricing changes affect the API surface: a price change that also changes what API capabilities are included in each tier requires coordinated changes to the billing system and the API entitlements system.

What ties these five sections together is the same insight that the platform engineering decision record surfaces about internal developer platforms: the billing system is chosen when requirements are simple and extended incrementally until the cumulative weight of extensions, undocumented conventions, and deferred design decisions makes the system difficult to change at exactly the moment — a pricing experiment, a compliance audit, an enterprise deal — when the team most needs to change it quickly. The decision record does not prevent the system from evolving. It makes the evolution deliberate: the team knows what the current architecture covers, what it does not, when they have exceeded its design basis, and what the redesign requires. That information, captured at decision time, is worth more than the two days of engineering effort the decision record requires to write. The alternative is discovering the gaps under deadline pressure, at the cost of weeks of engineering work and, occasionally, the cost of a deal that couldn't wait.

What to do with the billing architecture decision record

The billing architecture decision record is not a one-time document. Billing systems change — new payment methods are added, pricing models evolve, tax obligations expand as the company grows into new markets, the revenue recognition model becomes more complex as contract structures become more varied. The decision record should be updated when the billing architecture changes meaningfully: when usage-based billing is added, update the metering data model section; when a payment abstraction layer is introduced, update the processor coupling section; when the company crosses a tax nexus threshold and adds automated tax collection, update the tax handling section.

The record's primary value is for the engineers and finance staff who inherit the billing system rather than the people who built it. A billing system that was designed three years ago by engineers who have since left — which describes most billing systems — is an opaque system in which the reasoning behind every design choice has evaporated. Why does the system have forty Stripe Price objects? Why does the reporting service aggregate revenue from three different Stripe object types rather than one? Why is the usage aggregation job scheduled at 11:45 PM rather than midnight? The decision record answers these questions because it was written by the people who made the choices, at the time they made them, with access to the reasoning that informed the choice. Without the record, the engineers who inherit the system must reconstruct the reasoning from code comments, git history, and conversations with whoever is still available — a process that takes days rather than minutes and produces a reconstruction that is never as complete as the original.

If your billing architecture was built without a decision record, the most useful starting point is not to write a comprehensive historical account of every decision ever made — that reconstruction project will never be finished. The most useful starting point is to answer three questions today: what is the current billing architecture's revenue model ceiling (what pricing model could the product team not launch without a billing architecture change?), what is the current payment processor abstraction level (how many services make direct Stripe API calls, and what would the migration scope be if those calls needed to change?), and what is the current pricing iteration mechanism (how long does it take, in engineering days, to add a new pricing tier?). Those three answers, captured in a one-page document and stored where the billing code lives, are the billing architecture decision record that the next engineer to touch the billing system will find most useful. Build on it from there. The ADR template provides a starting structure. The WhyChose extractor can surface billing-related decisions already documented in your AI chat history — the billing architecture discussion that happened in a Slack thread or a ChatGPT conversation eighteen months ago may contain the reasoning you need to reconstruct the original intent. The decisions never written down essay covers why billing is one of the categories most likely to have critical undocumented reasoning, and why that gap is worth closing before the next pricing sprint.