Subscription and Usage Based Billing

The part that decides whether the whole thing survives contact with customers is much less glamorous. A customer will eventually query a line on their invoice, and at that moment you need to produce a record of what they did that you are prepared to stand behind, event by event, in front of somebody who has every incentive to find a discrepancy.

That is a data problem, not a pricing problem. And the specific thing that makes it hard is unremarkable enough to be easy to underestimate: the same event will arrive twice. Networks retry. Functions get torn down mid-request and restarted. A queue redelivers because the acknowledgement was the message that got lost. Any of these turning into a second charge is a support ticket at best.

The important design choice is what happens to that key next. It becomes the primary key of the row in the sink, rather than a value stored in a separately indexed column and checked before writing. Read that difference twice, because it is the entire mechanism: the database itself refuses the duplicate as part of the insert. There is no window between checking and writing for a concurrent retry to slip through, and no dedup service to keep available.

The cost of that design is real and it is documented rather than buried. Two genuinely distinct events that are identical down to the millisecond collapse into one row. That is an undercount, chosen deliberately. When a billing system has to be wrong, it should be wrong in the direction that does not appear on a customer's card.

A batch leaves the buffer when it fills, 500 events by default, or when the oldest event in it reaches the flush interval, five seconds by default. Back pressure kicks in at ten thousand buffered events. A batch that fails to write goes back to the front of the queue rather than the end, so a transient failure does not quietly reorder your log. A scheduled job flushes every minute regardless, which catches the low-traffic case where a batch would otherwise sit half full.

Buffered events live in memory. A hard kill loses whatever has not been flushed, unless immediate flush mode is enabled, and that trade is yours to make per meter rather than ours to make for you. A high-volume meter usually wants the buffer. A meter counting something expensive and infrequent usually does not.

Rating runs against a rate card carrying a unit amount, a per-units divisor for the meters where the natural unit is a thousand of something, and an included-units allowance for the bundled quantity your plans come with. Closing a period freezes its result, and that freeze is what turns a running total into a number you can send to somebody.

Corrections are appended, never applied in place. A mistake is fixed by writing a reversal with a negative quantity, so the log records both what was originally counted and what was later decided about it. There is no update and no delete anywhere in this design, which is inconvenient exactly once, in the moment you would rather just fix the number, and valuable every time afterwards.

One boundary is worth stating plainly rather than leaving you to discover it. medusa-usage does not issue invoices, and it ships no scheduler for closing periods. It produces frozen, rated period results. Turning those into documents and payments is separate work, and we would rather scope it honestly than let the word billing do more implying than it should.

For those, medusa-usage-tinybird sends the same events to Tinybird on ClickHouse. It ships the schema itself, one data source and three endpoints, so adopting it is not a data modelling project handed to you. Installing it is opt-in, and a deployment that never does is unaffected in every respect.

ClickHouse has no primary key constraint, so the deduplication has to move somewhere, and it moves to the read path. Every endpoint collapses duplicate keys before summing, keeping the earliest ingested copy of each. That is the same copy the PostgreSQL sink keeps, so the two sinks agree by construction rather than by luck. The declared token carries append on the data source and read on the endpoints, and nothing else.

We build it with a durable outbox. Each batch is written to the outbox before the first send is attempted, which means a serverless function torn down mid-request costs a delayed delivery rather than a hole in the log. An hourly job drains whatever the inline attempt did not finish, so recovery is routine rather than a manual investigation.

The other rule is that Medusa is the single writer of the deduplication key. The reporting application never appends to the log directly, so the key is derived in exactly one place. Two derivations mean two chances to disagree, and a disagreement in a deduplication key is not a bug you find quickly.

This is not a diagram from a proposal. It is how our own platform's subscription and usage billing is put together, on a Medusa store we host ourselves.