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 you sell, what it costs, 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
A new organisation's onboarding checklist follows the same sequence as this section.
- 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 each subscription line either pins the version it was sold on or follows newer ones, as the deal says. 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.