Blog

Notes from the billing layer.

Short engineering notes about subscription billing, payment provider behaviour and the decisions behind the product. No fabricated case studies or customer quotes.

6 min read

Why a renewal is a sequence, not a status field

Most billing systems store a subscription status and change it when a charge succeeds. That model breaks down the moment a payment is retried, partially refunded or applied to a credit balance. This note describes the state machine Sobtra uses instead, and why every step produces a record that can be audited later.

The tempting model is a column: `status = active | past_due | cancelled`. It is easy to query and easy to render. It is also the reason most support conversations about billing start with someone reading three different screens and finding they disagree.

Sobtra treats a renewal as a sequence of records: a billing period closes, an invoice is created, a payment attempt is made, and the result is recorded against both the invoice and the subscription. The subscription's own state is derived from those records rather than written directly. That means a retry does not overwrite a failure, and a refund does not erase the original payment.

The trade-off is more tables and more joins. The benefit is that when a merchant asks why a customer was charged twice, the answer is in the data rather than in someone's memory.

4 min read

Idempotent usage ingestion, and why we count duplicates separately

Metered billing only stays honest if retried requests are not billed twice. We considered deduplicating silently and instead chose to report duplicates back to the caller.

When an event arrives, Sobtra checks its externalId against the meter. If it has been seen before, the event is rejected and reported as a duplicate in the response. It is not silently ignored.

Silent deduplication is easier to implement and easier to like. The problem is that a client which sends the same event twice because of a bug never learns that anything was wrong. Reporting the duplicate means the client can fix the bug, and it means our own ingestion numbers can be reconciled against the client's numbers.

The limit is 500 events per batch. That is a pragmatic cap rather than a technical one: large batches make partial failures expensive to reason about, and most products do not need to send more than that in a single call.

Publishing cadence. Notes appear when there is something to say. We do not pad the calendar with content marketing, and we do not publish customer stories we do not have.

Also useful

Documentation and guides.