Decide what a customer is paying for
Suppose a SaaS product charges for completed report pages. A worker attempt is not necessarily a completed page: a retry can deliver the same completion twice, and a later review can invalidate some of the reported work. Before connecting an invoice system, the product team needs a defensible answer to one question: which events count toward this customer's usage period?
The executed ledger fixture uses six deliveries for one fictional customer and meter. Two are duplicates. Four unique entries produce 150 units across two periods, whereas simply summing every delivered payload produces 230. These are assigned examples, not observed customer usage or a pricing recommendation.
The contract in this example counts completed pages, attributes them to the period of completion and permits a linked correction while that period remains open. That combination is a product decision. Counting attempted work, attributing late events to their arrival period or handling an already-issued invoice would require different rules.
Keep delivery identity separate from billable meaning
An event needs enough identity to survive retries without confusing two legitimate completions. Here, the deduplication key combines tenant, meter and event ID. Repeating the same key with the same payload is a duplicate delivery. Repeating it with different content is an error requiring investigation, not permission to overwrite the earlier entry.
The fixture accepts 100 May units as event u1 and 40 June units as u2. A repeated delivery of u1 adds nothing. A late event u3 contributes another 30 May units because its occurrence period is May. The code does not use arrival order to redefine the customer's accounting period.
That rule must be visible to the people who answer billing questions. A dashboard grouped by ingestion day can be operationally useful while disagreeing with a usage statement grouped by service period. Label the two views and preserve the underlying timestamp evidence. Otherwise a legitimate late arrival looks like an unexplained change to yesterday's number.
Stripe's usage-recording documentation distinguishes recorded usage from asynchronously aggregated summaries. Its current guidance directs new usage-based implementations toward Metronome, while documenting Billing Meters for existing integrations. Treat the vendor's actual product and ingestion contract as a separate integration decision. An application ledger cannot assume that an external dashboard immediately reflects every accepted delivery.
A correction should identify the fact it changes
The correction c1 removes 20 units from u1. It references the original usage entry, inherits its May attribution and leaves both records inspectable. Repeating c1 does not remove another 20 units. The resulting May total is 110: the original 100, minus the correction of 20, plus the late 30.
| Ledger event | Meaning | Applied change | Period |
|---|---|---|---|
| u1 | Completed pages | 100 | May |
| u2 | Completed pages | 40 | June |
| c1 references u1 | Linked correction | -20 | May |
| u3 | Late completion report | 30 | May |
The input deliveries and applied ledger make that arithmetic reproducible. Three additional checks reject an unknown correction reference, a correction exceeding the original event's remaining units and a conflicting duplicate payload. The script exits with an assertion failure if those boundaries stop holding.
This model only allows negative corrections against a previously accepted usage entry in the same tenant and meter. A correction cannot borrow units from another customer or silently change a different meter. Real products may also need positive adjustments, cancellation reasons, approval roles or evidence retention. Define those as explicit event types and permissions instead of stretching the meaning of a negative usage number.
The ledger is not a payment processor. It does not calculate prices, discounts, tax or an invoice balance. Its narrower job is to explain which usage facts contribute to a period and why a correction changes that total.
Make the customer-facing explanation an acceptance criterion
A useful usage screen can answer more than "what is the total?" For a disputed period, it should identify the counted work, show any correction and explain whether late arrivals can still change the number. Access to detailed evidence must follow tenant permissions. A support agent should not need unrestricted raw event access to explain a single customer's adjustment.
For this fictional product, an acceptance review starts with the exact sequence in the fixture. Product and engineering should agree that the two duplicate deliveries add no units, that c1 adjusts May once and that the late May event remains attributable to May. A screen showing only a running aggregate cannot demonstrate those properties.
When evaluating implementation help, connect that review to the scope actually offered. Pharos Production's SaaS development with usage tracking and subscription billing covers SaaS billing and subscription workflows alongside tenant isolation and usage tracking. The page is relevant when assigning responsibility for this product boundary. Ask a delivery proposal to demonstrate the original event, linked correction and tenant-scoped explanation before accepting a total-only billing integration.
That is a requirement for evaluating proposed work, not evidence that a provider ran this fixture or achieved a particular billing outcome. The commercial page does not replace acceptance evidence from your own implementation.
Choose the closed-period policy before the first dispute
The example assumes both periods are open. Once a customer has received a finalized statement, changing a historical aggregate may create a second meaning for the same displayed period. Decide how a late event or correction is represented at that point: a separately identified adjustment, a reopened period under a defined process or another supported product workflow.
Whatever the chosen policy, retain the connection between the new action and its original usage evidence. Do not erase the old event merely to make a current total match. Also define who can submit a correction and how a repeated request behaves after a timeout. The separate API idempotency example explains why retry identity must survive uncertain responses.
Before release, reconcile the application ledger with the external usage system using stable event identifiers and a known processing boundary. Accepted locally, transmitted remotely and included in a vendor summary are different observations. A missing remote aggregate may reflect delayed processing, a rejected event or an integration defect; the local ledger alone cannot distinguish them.
The fixture results establish four applied entries, two duplicate deliveries and the resulting period totals. They leave invoice policy and vendor behavior untested. That separation gives the team a concrete starting point: first agree on the customer's billable facts, then prove that the production integration preserves them.
Sources
Documentation checked .
Dreamtsoft Editorial
Support needs the completed-page definition. A worker attempt does not necessarily represent a completion. Retries make that distinction visible. I would use the repeated-delivery example when reviewing the usage screen. The explanation should identify the completed work that actually counts.
Dreamtsoft Editorial
A repeated identifier with changed content needs investigation. The deliveries disagree about the original usage fact. Treating that as an ordinary duplicate would hide the disagreement.
Dreamtsoft Editorial
The late event belongs to its occurrence period under this contract. A view grouped by ingestion day needs a clear label so it does not appear to contradict the usage statement.
Dreamtsoft Editorial
Keep the correction linked to its original entry. A lower aggregate leaves the customer asking which work was removed. The link identifies that work. The adjustment then has an explanation beyond the changed total.
Dreamtsoft Editorial
Repeated corrections need retry checks that distinguish the link identifying what changes from the durable event identity controlling whether it changes again.
Dreamtsoft Editorial
What should support show when a correction arrives after period closure? The open-period fixture leaves that decision unresolved. I would add a closed-period acceptance case. Preserve the original usage evidence in it. The displayed adjustment should explain how the chosen policy handles that earlier period.
Dreamtsoft Editorial
Check tenant scope on correction references. Check meter scope too. An identifier can exist outside the intended scope. Its existence alone cannot supply the usage evidence for this adjustment.
Dreamtsoft Editorial
Local acceptance and inclusion in an external summary are separate checkpoints. A reconciliation view needs the event identity that connects them. That gives the reviewer a way to locate where a missing contribution stopped.
Dreamtsoft Editorial
Keep pricing rules separate when reviewing an implementation proposal because this ledger explains usage units without establishing an invoice balance.