Dunning
Dunning is what happens when an invoice is not paid. It is the sequence of retries and reminders that runs after the due date passes, so that most late payments resolve themselves before anybody opens a spreadsheet.
Kontier treats dunning as a phase of the subscription, not
a status. A subscription being chased is still ACTIVE, carrying a phase of kind
dunning. That matters when you go looking for it: filtering by status will not
find it.
What starts and ends it
An invoice becomes overdue when its due date passes with a balance
outstanding. That is the trigger.
From there the policy decides how often to retry a failed payment method, when
to email the customer, and what to do if nothing works. It ends in one of three
ways: the invoice is paid and the subscription returns to its standard phase,
the sequence is exhausted and the subscription is cancelled or suspended, or
somebody intervenes.
Dunning is a phase, not a status
SubscriptionStatus is only DRAFT, ACTIVE and CANCELLED. A subscription in
dunning is ACTIVE with phase_kind: "dunning" and a dunning_stage recording
how far through the sequence it has got. See
Subscriptions.
Set it up in the dashboard
Dunning is configured per organisation, and a plan can carry its own policy for the subscriptions on it.
-
Open organisation settings
In the sidebar under Configuration, click Organization.
-
Go to Billing & Money
Dunning sits with currencies, FX, wallets, payment gateways and promotions, because it is a money-movement concern rather than a catalog one.
Organization → Billing & Money, where dunning is configured -
Set the retry sequence
How long after the due date the first retry runs, how many attempts follow, how far apart, and what happens when they are exhausted.
-
Decide what the customer receives
Each stage can send mail. The wording lives in your email templates, so the policy decides when and the template decides what.
Watch it from the API
Invoice state is public, so the reliable way to observe dunning through the API is the invoice and the subscription phase:
Dunning policy is not in the public API yet
The endpoints that configure dunning are operator-only while we finish tidying them up, so they are not in the public reference. Configure it in the dashboard. If you need to manage dunning policy from your own system, email engineering@kontier.eu and we will talk you through the options.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| an invoice past its due date | status: "overdue" |
| a subscription being chased | active phase with phase_kind: "dunning" |
| how far through the sequence | dunning_stage on that phase |
| Organization → Billing & Money | operator-only configuration |
Where dunning goes next
- A payment arrives and the subscription returns to its
standardphase. - Nothing arrives and the sequence ends in cancellation or suspension, according to your policy.
- You write it off with a credit note using reason code
GOODWILLorOTHER, which keeps the audit trail honest.
Next step
Continue to Webhooks to react to payment failures in your own system as they happen.
Reference
| Topic | When you need it |
|---|---|
| Subscriptions | Phases, and why dunning is one |
| Payments | Why a payment failed in the first place |
| Credit notes | Writing off what will not be collected |
| Invoices API | Invoice status, the public signal for overdue |