How a period is billed
Objective
Section titled “Objective”What you are actually promised about your bill. Most clouds never write this down; the mechanics are worth knowing because they tell you what a disputed line can and cannot be.
The unit is one project-hour
Section titled “The unit is one project-hour”The billing ledger holds one row per project per hour — the unit that is sold. A row records the hour it covers and the amount rated for it.
Everything below is about the life of one such row.
An unbilled hour converges; a billed hour is frozen
Section titled “An unbilled hour converges; a billed hour is frozen”| State | What a re-collection does |
|---|---|
| Not yet billed | Takes the rating system’s latest word. A partially rated hour corrects itself |
| Already billed | Frozen. The recorded amount never changes |
That is the central rule: what you were told is what the ledger keeps saying. A number cannot be revised underneath an invoice you have already received.
Rating an hour is not instantaneous, so an hour collected early may be rated incompletely. While it is unbilled it keeps converging on the true figure. Once it has been billed it stops moving, permanently.
A zero-rated hour is not a sale
Section titled “A zero-rated hour is not a sale”An hour that rates to zero is never recorded. The ledger records what was sold, and nothing sold is not a row.
If an hour was recorded and then walked back to zero before it was billed, the stale row is deleted outright — you are not invoiced for an hour that turned out to be nothing.
If it had already been billed, the row is left exactly as it was. See the next section for what happens then.
When a rate changes after you were billed
Section titled “When a rate changes after you were billed”This is the interesting case, and it is handled explicitly rather than swept up.
If the rating system later reports a different amount for an hour you have already been billed for:
- The ledger row does not change. You were told a number; that number stands.
- You are not silently re-billed, and no correcting charge appears without anyone noticing.
- The discrepancy is recorded as an error naming both the frozen amount you were billed and the new amount now reported, so a person reconciles it deliberately.
The design choice worth noticing: a re-rate is neither applied silently nor discarded silently. Both of those would be easier. It is raised for a human, because a bill that changes on its own is worse than a bill someone has to look at.
If you dispute a line, that record is what the dispute is resolved against.
Never billed twice
Section titled “Never billed twice”Before an hour is reported for billing it is marked as in flight. If a tick crashes between reporting and confirming, the next tick can see that the attempt was already made and does not report it a second time.
The ledger is the guard, not the retry logic. That is why a failed run is safe to simply run again.
When an hour fails to bill
Section titled “When an hour fails to bill”| Outcome | What happens |
|---|---|
| Retryable failure — the billing provider did not answer, or no customer record existed yet | The hour is marked as having failed and rotated to the back of the queue, so one stuck hour cannot block every other |
| Permanently unbillable | The hour is closed without being billed, with the reason recorded |
An hour becomes permanently unbillable when it falls outside the payment provider’s own acceptance windows — an event too old to accept, or an unconfirmed report past the window in which its identifier can still be deduplicated.
Those hours are dropped, not billed — and they are kept visibly distinct from hours that were billed normally, rather than being closed out to look the same. An hour that could not be charged is a fact about the system, and hiding it inside the “done” pile would make it unfindable.
In practice this means it is possible for usage to go uncharged. It is recorded as such rather than quietly forgotten.
Backlogs drain slowly, on purpose
Section titled “Backlogs drain slowly, on purpose”A tick reports only a handful of hours. A long backlog therefore takes several hours to clear rather than emptying at once.
Combined with the rating delay, that is why
GET /v1/usage can be more than two hours
behind, and why a cost figure should never be treated as real-time.
What this gives you
Section titled “What this gives you”- An invoice line, once issued, means the same thing forever.
- You cannot be double-charged for an hour by a retry.
- You cannot be charged for an hour that rated to nothing.
- A change of mind after the fact is surfaced, not applied.
- A failure to charge is recorded, not hidden.
What it does not give you: real-time cost, a per-resource breakdown, or a guarantee that every hour is eventually charged.
Go further
Section titled “Go further”- Metering and invoicing — the chain end to end
- Usage and cost — the lag, in detail
- How prices are set — where the number comes from
- Billing user guide