Billing Is a Workflow, Not a Number
What I learned delivering usage-based billing and a platform-credit wallet, then reconciling the first production cycle.
People often describe billing as a calculation: take usage, apply a price, and create an invoice. In a production system, the calculation is only one part of the job. The system also has to account for credits, corrections, eligibility, and the point where a charge becomes an invoice.
At VTEX, I designed and delivered billing workflows for Master Data alongside a platform-credit wallet. The work covered credit accrual, consumption, reversal, expiration, and integration with invoice generation. Thinking through that full lifecycle changed how I approached the problem: each state had to make sense to the business and remain understandable when someone needed to explain a balance or investigate a charge.
Give every balance a clear story
A credit balance can change for several reasons. Credits can be added, used, reversed, or expire. Those are distinct business events. Treating them as one generic adjustment makes it harder to answer basic questions later: where did this balance come from, why did it change, and what should happen next?
The same applies to usage. A charge needs a clear relationship to the usage that produced it and to the invoice where it appears. When billing spans multiple services and datasets, those relationships are part of the product contract. They help engineers investigate discrepancies and help teams explain the result to customers.
That does not prescribe one storage model or one architecture. The right design depends on the existing platform. The useful starting point is to agree on the lifecycle and the questions the system must answer before choosing implementation details.
Reconciliation is part of operating the system
The first production cycle is a real-world check of the assumptions behind a billing system. After launch, I reconciled document usage, company, and invoice datasets to assess billing coverage. That analysis identified eligible accounts that had not been billed and about $51K USD per month in additional potential net revenue for validation.
The phrase “for validation” matters. A discrepancy is a signal to investigate, not an instruction to issue an invoice. Reconciliation can reveal missing eligibility, timing differences, data-quality problems, or a real billing gap. The next step is to establish which explanation applies before changing customer charges.
For financial systems, operational checks should be designed alongside the happy path. Teams need a way to compare what was measured, what qualified for billing, what credits were applied, and what reached an invoice. Without that view, an accurate-looking invoice can still conceal a coverage problem.
Report outcomes with the right context
The first production billing cycle covered 2,358 companies, generated approximately $393K USD in net monthly revenue, and applied approximately $162K USD in platform credits. The analysis also identified total Master Data revenue potential of approximately $941K USD per month as temporary customer waivers expire.
These figures describe different things: realized revenue in the first cycle, credits applied, a potential billing gap under validation, and future revenue as waivers expire. Keeping those categories separate makes the results more useful and more trustworthy.
My main takeaway is that billing quality comes from the whole workflow. Model the business lifecycle clearly, make the result explainable, reconcile real production data, and label measured outcomes separately from estimates. The arithmetic still matters; confidence in the arithmetic is what makes the system dependable.