How Kontier fits together
This page is the map: which objects exist, and the order you build them in.
New to billing itself? Read How billing works first; it explains the domain rather than the product. Every term used here is defined in the glossary.
The shape of it
Three groups, built in one direction. Nothing in a later group works without the one before it.
| Group | Objects | What it answers |
|---|---|---|
| Catalog | Product → Price → Plan | What do we sell, what does it cost, what is sold together |
| Commitment | Customer + Plan → Subscription | Who is buying it, on what terms |
| Money | Subscription → Invoice → Payment | What do they owe, and did it arrive |
Around the edges sit the corrections: a credit note reduces an invoice, a wallet holds money paid in advance, and dunning chases what has not arrived.
Nothing bills until all three groups exist.
Build it in this order
The product itself keeps the same list. A new organisation shows a checklist on its dashboard, and it is the same sequence this section documents.
- Create a product. The thing you charge for; its type decides where the billed quantity comes from.
- Attach a price. Money, in a currency, optionally with a tier ladder. A product without one cannot be sold.
- Publish a plan. Priced products bundled into something subscribable. Editing a plan does nothing until you publish a version.
- Add a customer. Their type decides how tax is calculated.
- Subscribe them. This is where catalog becomes revenue.
- An invoice appears at the end of each billing period. Finalising it makes it immutable.
- Take the payment through a gateway, a wallet, or by hand.
When it goes sideways
The happy path above is four pages long. The rest of this section is what happens when reality intervenes.
| Situation | Page |
|---|---|
| You billed the wrong amount | Credit notes |
| They did not pay | Dunning |
| They pay in advance | Wallets |
| You want to discount | Promotions |
| You bill for consumption | Usage |
| Tax is not one rate | Taxes |
| You need to react in your own system | Webhooks |
Two Kontier invariants
Neither is general billing practice; both are specific to how Kontier works, and both are cheaper to learn here than from an invoice.
Versioning is everywhere
Six things carry versions: plans, products, promotions, tax rules, rate tables and price formulas. Prices, meters and costs do not. Editing a versioned thing changes a draft, not what customers are being sold; publishing is a separate, deliberate act, and a subscription pins the version it was sold on so publishing cannot disturb it. See Versioning.
Money is a string
Every amount in the API is a string like "159.00", in major units, in an
explicit currency. Never 15900, never a float. This is deliberate: binary
floating point cannot represent money exactly, and rounding errors in billing are
not recoverable.