Ledger

Services

The decision worth arguing about

The non-obvious decision is what happens to a metering event that arrives after its billing period has closed, and it is the decision that separates a billing system your finance team trusts from one they quietly reconcile in a spreadsheet. Usage events arrive late for entirely ordinary reasons: a customer's own batch job, a network partition, a collector restart. The intuitive handling is to accept the event, recompute the period's usage and reissue the invoice. That is the wrong answer, because a reissued invoice is a restatement — it breaks the numbers already posted to the general ledger, already reported to the board, already used in a revenue schedule, and in some jurisdictions it breaks the invoice numbering sequence's legal integrity. So Ledger closes a period hard: metering events carry a client-supplied idempotency key with a unique index, they are aggregated into period buckets incrementally as they arrive, and an event whose timestamp falls inside a closed period is accepted, stored, and rated as a dated adjustment line on the next invoice rather than reopening the last one. The trade-off is that a customer occasionally sees usage from March on their April bill, so the adjustment line carries its original period on the invoice and the portal explains it — a small presentational cost in exchange for invoices that are immutable once issued. Kinesis carries the metering firehose rather than SQS because ordering per subscription matters for stairstep and tiered models where the sequence of usage determines which tier applies, and the shard key is the subscription id. Two smaller points that are not negotiable in a billing system: every monetary value is an integer in minor units and every rating computation uses Postgres numeric, because a float rounding error of a hundredth of a cent across forty million events a month is not a rounding error, it is a reconciliation failure someone spends a week finding; and invoice PDFs go into an Object Lock bucket, because 'the invoice we sent' and 'the invoice we would generate today' must be provably the same document.

Services

The decision worth arguing about

The metering firehose is where Azure imposes a decision you cannot walk back, and it is the reason this section exists rather than saying 'as AWS, with Event Hubs'. Event Hubs is the Kinesis equivalent and it is a good one, but on the Standard tier the partition count is fixed when the hub is created and cannot be changed afterwards — increasing it is a Premium and Dedicated capability. Partition count is also what caps your consumer parallelism, and because per-subscription ordering matters to tiered rating, the partition key has to be the subscription id, which means a busy customer's events all land on one partition and that partition's throughput is your ceiling for that customer. Get the number wrong at creation and the fix is creating a new hub and migrating producers and checkpoints across, mid-flight, on a system that is metering revenue. So we over-provision deliberately at thirty-two partitions for the reference org's forty million events a month, well beyond what the throughput needs, purely to buy headroom we cannot buy later. The cost of that is not the partitions themselves but the checkpoint overhead — each consumer instance holds lease and offset state per partition, so a sparsely-loaded thirty-two-partition hub does more bookkeeping per useful message than an eight-partition one would, and the consumer group's rebalance on deploy takes longer. We accept slower rebalances and slightly higher idle overhead in exchange for never having to migrate a live billing firehose. Everything else ports cleanly: Blob immutability with a locked time-based policy gives the same guarantee as S3 Object Lock for invoice documents, Key Vault holds processor credentials, and the rating and revenue recognition modules are pure functions with no cloud dependency at all, which is deliberate — the part of this system that must be provably correct is the part that should be testable on a laptop.