How billing works
Billing looks simple from outside: send a bill, take the money. Inside, it is a chain of decisions about what is owed, when it is owed, and when it counts as revenue, and each of those is a different question.
This page explains the domain. It is not about Kontier's API; it is about the ideas every billing system has to model, with the words Kontier uses for them.
| If you… | Go to |
|---|---|
| already know billing and want the object map | How Kontier fits together |
| just want to build something | Products |
| are choosing a pricing model for your business | Business models |
The chain
Code
Catalog is what you sell and what it costs: a product, a price, and a plan bundling them. It is a description, not a commitment. Nothing in the catalog belongs to a customer.
Subscription is the commitment: this customer, this plan, these quantities, this cycle. It is where a description becomes an obligation. A subscription pins the plan version it was sold on, so changing the catalog cannot silently reprice someone.
Usage is what actually got consumed, for anything measured rather than declared. Usage is recorded as events and aggregated later, because you cannot know the total until the period ends.
Invoice is the bill: the arithmetic of the period, frozen. Once issued it is immutable, because it is a legal record and not a view of current data.
Payment is the money arriving, which is a separate event from the bill and can be earlier, later, partial, or from several sources at once.
What a charge is made of
Every line on an invoice is the same shape:
Code
The interesting part is where each side comes from.
Quantity is either declared or measured. A declared quantity is stated and holds until somebody changes it: twelve seats stays twelve seats. A measured quantity is counted by a meter and resets each period: this month's API calls have nothing to do with last month's.
Price can be a single amount or a ladder of tiers that changes the rate as quantity grows.
Kontier puts the pricing model on the product
How a tier ladder is read is a property of the product, not the price. Stripe and Orb put it on the price. If you are migrating, this is the first thing that will surprise you: two prices on one product are always read the same way. See Pricing models.
When money is charged
Two timings, and the difference is not cosmetic.
| Charged | Suits | |
|---|---|---|
| In advance | At the start of the period | Flat fees, seats: the amount is known up front |
| In arrears | At the end of the period | Usage: the amount cannot be known until it ends |
Measured usage is always in arrears. There is no way to bill for consumption that has not happened yet, which is why usage-based businesses carry more collection risk than seat-based ones.
Two dates matter and are often confused. The billing period is the span of time being charged for. The billing anchor is the day of the month the cycle turns over. A subscription started on the 31st with an anchor of 28 bills on the 28th, because not every month has a 31st.
When the amount changes
A customer who adds ten seats on day fifteen has not bought a month of ten seats. Proration is how the difference is settled: the unused part of what they already paid is credited, and the new amount is charged for the remaining days.
Code
Two ledger lines, not a recalculated invoice. That matters because the original charge already happened and cannot be edited. Changes that should take effect later rather than now are held as scheduled changes.
Invoice, revenue and cash
The single most common confusion in billing, and worth ten seconds of care.
| What it means | When it happens | |
|---|---|---|
| Invoiced | You issued a bill | The moment the invoice is finalised |
| Cash | The money arrived | Whenever the customer pays, or never |
| Revenue | You earned it | As the service is delivered, spread over time |
Bill a customer €1,200 in January for a year. You invoiced €1,200 in January, you may receive €1,200 in January, and you earn €100 a month for twelve months. Three different numbers from one event.
Money taken before it is earned is a liability, not income. That is what a prepaid wallet balance is: your customers' money, sitting with you.
Recognising revenue formally is governed by IFRS 15 and ASC 606, whose five-step model runs from identifying the contract to recognising revenue as obligations are satisfied. Kontier does not do revenue recognition for you. It records what was invoiced and what was paid, accurately enough that your accounting system can.
When payment does not arrive
Not all churn is a decision.
Voluntary churn is a customer choosing to leave. Involuntary churn is a payment failing on a customer who intended to stay: an expired card, a changed bank, a limit hit. For many subscription businesses involuntary churn is the larger number, and it is the recoverable one.
Card failures split in two, and the distinction decides what you do:
- A soft decline is temporary. Insufficient funds, an issuer timeout. Worth retrying, which is what dunning automates.
- A hard decline is permanent. Closed account, stolen card. Retrying it will never succeed and repeated attempts can be penalised. The customer has to supply a new method.
Words that differ elsewhere
If you are arriving from another platform, five words will trip you up.
| Word | Elsewhere | In Kontier |
|---|---|---|
| Price | Often the whole pricing object, tiers included | A money amount for one product, scoped by currency and country |
| Plan | Sometimes the price itself | A bundle of priced products, versioned |
| Pricing model | Usually a property of the price | A property of the product |
| Meter | Sometimes the raw event stream | The aggregation rule over events, not the events |
| Trial | Often a subscription status | A phase on an active subscription, not a status |
Every term used here is defined in the glossary.
Where the numbers come from
Metrics like MRR and churn have no single agreed definition, so two tools will disagree and both be right. Kontier's analytics count MRR from active subscriptions in one currency at a time, and a subscription in a trial counts because a trial is a phase and not a status.
Before reconciling with another system, compare definitions rather than numbers.
Related
- How Kontier fits together — the same chain, as Kontier's objects
- Glossary — every term, one sentence each
- Business models — worked blueprints for real businesses