Invoices
An invoice is the bill. Kontier generates one automatically for each subscription at the end of its billing period, assembling recurring charges, metered usage, prorations from mid-period changes, any promotions that apply, and tax.
You will rarely call the generate endpoint yourself. The scheduler does it at
current_period_end, which is the normal path. Manual generation exists for
one-off bills and for reissuing.
The lifecycle
An invoice has six states: draft, finalized, paid, void, overdue and
error. Only one transition really matters, and it cannot be uncrossed.
Draft
Editable. Lines can be added, changed and removed. Nothing has been issued and the customer has seen nothing.
Finalized
Immutable. Numbers are assigned, tax and exchange rates are pinned, and the document becomes the legal record. An issued invoice cannot be edited, because under German commercial law (§ 14 UStG / GoBD) it must not be.
To correct a finalised invoice you issue a credit note or void it. You do not edit it.
Paid, overdue, void
paid when the balance reaches zero. overdue when the due date passes with a
balance outstanding, which is what starts dunning. void when it is
cancelled outright rather than corrected.
Finalising is the decision point
Everything before it is reversible; nothing after it is. Check the lines, the customer's tax identity and the currency while the invoice is still a draft.
What a line is made of
Each product on the subscription becomes a line carrying the quantity, the unit price, the tax rate and the resulting amount.
Under each line sits an audit trail of atoms: the individual computations that produced it. That is where the exchange rate and the tax decision for that line are recorded, which is what makes a finalised invoice reproducible years later.
Use it in the dashboard
-
Open the billing page
In the sidebar under Billing, click Billing. Invoices and credit notes are two tabs on the same page.
-
Filter by status
The tabs across the top are the lifecycle: Draft, Finalized, Overdue, Paid, Partially paid, Voided, Error. Overdue is the one to watch.
-
Check a draft before finalising
Open the invoice and read the Line Items tab. Confirm the customer, the currency and the tax summary, then finalise.
-
Record a payment if it arrived outside a gateway
Bank transfers and cheques do not come back through a provider, so record them against the invoice. See Payments.
Use it over the API
Only subscription_id is required to generate. Omit the period and the current
open period is used. locale picks the language of the rendered document.
Preview is free, generate is not
preview returns the line set without persisting anything. Use it to check what
a period will produce before it produces it.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Draft → Finalized | POST /invoices/{id}/finalize |
| Status filter tabs | status: draft, finalized, paid, void, overdue, error |
| Balance column | what is still owed, as distinct from Amount |
| Record Payment | POST /invoices/{id}/record-payment |
| E-Invoice column | the EN 16931 / XRechnung export state |
| Actions → download | GET /invoices/{id}/pdf |
Where invoices go next
- Take the money, through a gateway or by recording a manual payment.
- Correct mistakes with a credit note, never by editing.
- Chase what is late once an invoice goes overdue.
Next step
Continue to Payments to settle what you have just issued.
Reference
| Topic | When you need it |
|---|---|
| Credit notes | The only way to correct a finalised invoice |
| Taxes | How the rate on each line was chosen |
| Exchange rates | Which FX rate is pinned, and when |
| E-invoicing | EN 16931 and XRechnung document generation |
| Invoices API | Every field, plus lines, refund, regenerate and PDF |