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. Kontier drafts the invoice
when a billing period of the subscription closes, which is the normal path.
POST /v1/invoices/generate exists to draft a period on demand, and
POST /v1/invoices creates a standalone draft for a one-off bill that belongs to
no subscription.
The lifecycle
An invoice's status is one of draft, finalized, overdue, paid,
reversed, uncollectible and discarded. Only one transition really matters,
and it cannot be uncrossed.
Draft
Editable. Manual charges can be added, changed and removed, and quantities,
unit prices and headings can be overridden. Nothing has been issued and the
customer has seen nothing. A draft has no number yet. A draft you do not want is
thrown away with POST /v1/invoices/{id}/discard (status discarded), which
makes its period billable again.
Finalized
Immutable. The number is minted, 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
reverse it whole with POST /v1/invoices/{id}/void, which mints a credit note
against it. You do not edit it.
Paid, overdue, reversed, uncollectible
paid when the balance reaches zero. overdue when the due date passes with a
balance outstanding, which is what starts dunning. reversed when a
credit note has taken the whole document back. uncollectible when you write it
off with POST /v1/invoices/{id}/write-off: nothing is reversed and the balance
still stands, but you do not expect it to be paid.
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
Over the API, list invoices with GET /v1/invoices and finalize a draft with
POST /v1/invoices/{id}/finalize; see Use it over the API.
-
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
To generate from a subscription, subscription_id is enough: the customer and
currency come from the subscription. period_start and period_end name the
billing period; a period that already carries a live document is refused unless
replace_draft says to replace the draft standing in it. locale picks the
language of the rendered document. A standalone draft (POST /v1/invoices)
needs customer_id and currency, and takes optional entries inline.
Preview is free, generate is not
preview runs the same assembly as the draft and returns the lines and atoms
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, overdue, paid, reversed, uncollectible, discarded; Partially paid is the partially_paid list filter |
| Balance column | amount_due, what is still owed, as distinct from total |
| 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, overrides, refund, regenerate and PDF |