Per-Unit Billing Is a Domain Model Before It Is A Payment Integration

Before you wire a card processor, answer four domain questions: what a billable unit is, when quantity changes take effect, how proration behaves, and how usage reconciles with service state. These are product decisions first and integration work second.

Billable units must be explicit identities

Treat a billable unit as a domain object with an identity you can reference in events, invoices, and customer conversations. “Billable unit identity” is not the same as a SKU, a product name, or a database primary key — it is an immutable token a human and machines can agree on.

Concrete properties for a billable unit:

• stable unique id (opaque string), human label, and canonical description
• unit of measure (count, GB, minutes, ports)
• billing granularity (per-second, per-minute, per-month, per-invoice)
• pricing dimension (tiered, volume, flat, per-unit)
• lifecycle states (provisioned, suspended, terminated)

Why this matters: billing decisions should not be spread across invoices, usage collectors, and product pages. If the product UI calls something a “port” while invoicing calls it a “connection”, you will get disputes and incorrect credits.

Effective dates and proration are policy, not math

Decide when a quantity change takes effect and codify a proration policy. “Effective dates and proration” belong in your domain spec because edge cases are product-policy, not accounting magic.

Common options:

• immediate: change affects the current billing interval at the timestamp of the event
• period boundary: change takes effect at the next billing cycle
• scheduled effective date: explicit date provided by user

Proration behaviors to pick from:

• invoice-level prorate (single line item split across periods)
• account credit/charge (create a credit for unused time)
• no proration (useful when pricing is approximate or to simplify UX)

Costs and failure modes: immediate proration increases implementation complexity (requires fine-grained meters and partial-line invoicing) and a larger reconciliation surface. No proration simplifies integration but can produce larger “surprise” invoices.

The source of truth should be a single system of record

Designate one system as the “source of truth” for billable state — whether that is your product database, a billing microservice, or a metering ledger. All adapters (usage collectors, UI, payment provider syncs) must converge against it.

Requirements for the source of truth:

• write-after-validate API for intent changes (create/adjust/terminate)
• immutable historical events or append-only ledger for auditability
• projection(s) that present the current billing quantities and effective dates
• exportable reconciliation reports

Adapters are thin: they translate external events into domain events that the source of truth accepts. This minimizes race conditions and keeps trust constrained.

Usage collection, reconciliation, and invoices are separate responsibilities

Treat metering, rating, and billing as separate stages. Metering captures raw events; rating applies pricing rules to produce billable quantities and monetary amounts; billing aggregates rated usage into invoices.

Invoice-generation sequence (high level):

1. Close interval / snapshot billed quantities using effective dates
2. Apply pricing rules (including discounts, tiers)
3. Create invoice draft with line items and proration adjustments
4. Persist invoice and publish to payment adapter or accounting system

Invoice reconciliation and disputes need a clear mapping from invoice line items back to billable unit identity and source events. If a customer disputes a charge, you must be able to show the recorded events, the effective dates used, the pricing rule applied, and the invoice line that consumed the quantity.

Disputes and audit trails win on traceability, not blame

Design invoice reconciliation and disputes as a process that answers: Where did this quantity come from? Why did it bill now? What happened to the unit’s state?

Operational acceptance criteria for disputes:

• every invoice line references a billable unit id and an event window
• you can re-run rating for a given window and produce the same (or explainably different) amounts
• credits and adjustments are recorded as domain events with causal links

Failure modes: loose references (“service X billed Y GB”) force human triage. No event replay or immutable logs makes reconciliations guesses. Build the minimum traces that let an engineer, a support agent, or an auditor reconstruct the billable path.

A practical decision checklist (reusable)

Use this checklist when designing or reviewing a per-unit billing flow.

• Billable Unit Identity
  • Is there a stable opaque id for each billable unit?
  • Is the unit of measure and granularity recorded with the id?
• Effective Dates & Proration
  • Policy chosen: immediate / boundary / scheduled?
  • Proration behavior specified for upgrades, downgrades, and cancellations?
• Source of Truth
  • One system designated for billable state and events?
  • Write API uses validation and returns causal ids?
  • Immutable event log or ledger exists for audits?
• Metering & Rating
  • Metering captures raw events with timestamps and unit ids?
  • Rating rules are versioned and can be re-run deterministically?
• Invoicing & Reconciliation
  • Invoice lines reference billable unit ids and event windows?
  • Reconciliation report maps invoice lines back to raw events?
  • Dispute process documents steps, SLAs, and rollback approaches?

Use the checklist as a gate in design reviews; if a single box is unchecked your integration work will be harder.

Takeaway

Per-unit billing is primarily a product-domain design problem before it becomes a payment integration. Define billable unit identity, pick and document effective dates and proration, keep a single source of truth for billable state, and design invoice reconciliation and disputes around traceability and deterministic reruns. These decisions reduce ambiguity, shrink the blast radius of billing bugs, and make disputes resolvable with evidence rather than guesswork. For help turning a billing decision into an audit-ready implementation, /contact