Dunning

Endpointhttps://api.kontorion.eu/v1

Dunning is the automated process of recovering failed payments. When an invoice payment fails, the dunning policy defines a sequence of escalating actions - retry the payment, send reminder emails, and eventually cancel the subscription if payment isn't recovered.

How it works:

An invoice payment fails
The dunning policy's first step activates (e.g., retry after 3 days)
If the retry fails, the next step activates (e.g., send a reminder email after 7 days)
Steps escalate until payment succeeds or the final action triggers (e.g., cancel subscription after 30 days)

Dunning policies can be set at the organization level (default for all plans) or per-plan for different escalation paths.

Get the organization dunning policy

GET

https://api.kontorion.eu/v1

/dunning-policy

Returns the active dunning policy for the organization

Get the organization dunning policy › Responses

Wrapped in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

Create or update the organization dunning policy

PUT

https://api.kontorion.eu/v1

/dunning-policy

Creates a new dunning policy if none exists, or updates the existing one

Create or update the organization dunning policy › Request Body

name

string

object[]

Create or update the organization dunning policy › Responses

Updated policy in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

PUT/dunning-policy

curl --request PUT \
  --url https://api.kontorion.eu/v1/dunning-policy \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "steps": [
    {
      "action": "send_email",
      "days_after_due": 0,
      "email_event": "email_event"
    }
  ]
}
'

shell

Example Request Body

{
  "name": "name",
  "steps": [
    {
      "action": "send_email",
      "days_after_due": 0,
      "email_event": "email_event"
    }
  ]
}

json

Example Responses

{
  "key": {
    "created_at": "created_at",
    "deleted_at": "deleted_at",
    "id": "id",
    "is_active": true,
    "name": "name",
    "organization_id": "organization_id",
    "plan_id": "plan_id",
    "steps": [
      {
        "action": "send_email",
        "days_after_due": 0,
        "email_event": "email_event"
      }
    ],
    "updated_at": "updated_at"
  }
}

json

application/json

Delete the organization dunning policy

DELETE

https://api.kontorion.eu/v1

/dunning-policy

Soft-deletes the active dunning policy for the organization

Delete the organization dunning policy › Responses

No content

No data returned

Get a plan-level dunning policy

GET

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Returns the dunning policy override for a specific plan

Get a plan-level dunning policy › path Parameters

planId

string · required

Plan UUID

Get a plan-level dunning policy › Responses

Wrapped in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

Create or update a plan-level dunning policy

PUT

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Creates or updates a dunning policy override scoped to a specific plan

Create or update a plan-level dunning policy › path Parameters

planId

string · required

Plan UUID

Create or update a plan-level dunning policy › Request Body

name

string

object[]

Create or update a plan-level dunning policy › Responses

Updated policy in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

PUT/plans/{planId}/dunning-policy

curl --request PUT \
  --url https://api.kontorion.eu/v1/plans/:planId/dunning-policy \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "steps": [
    {
      "action": "send_email",
      "days_after_due": 0,
      "email_event": "email_event"
    }
  ]
}
'

shell

Example Request Body

{
  "name": "name",
  "steps": [
    {
      "action": "send_email",
      "days_after_due": 0,
      "email_event": "email_event"
    }
  ]
}

json

Example Responses

{
  "key": {
    "created_at": "created_at",
    "deleted_at": "deleted_at",
    "id": "id",
    "is_active": true,
    "name": "name",
    "organization_id": "organization_id",
    "plan_id": "plan_id",
    "steps": [
      {
        "action": "send_email",
        "days_after_due": 0,
        "email_event": "email_event"
      }
    ],
    "updated_at": "updated_at"
  }
}

json

application/json

Delete a plan-level dunning policy

DELETE

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Removes the dunning policy override for a specific plan

Delete a plan-level dunning policy › path Parameters

planId

string · required

Plan UUID

Delete a plan-level dunning policy › Responses

No content

No data returned

Billing Milestones Webhooks

How it works:

An invoice payment fails
The dunning policy's first step activates (e.g., retry after 3 days)
If the retry fails, the next step activates (e.g., send a reminder email after 7 days)
Steps escalate until payment succeeds or the final action triggers (e.g., cancel subscription after 30 days)

Dunning policies can be set at the organization level (default for all plans) or per-plan for different escalation paths.

Get the organization dunning policy

GET

https://api.kontorion.eu/v1

/dunning-policy

Returns the active dunning policy for the organization

Get the organization dunning policy › Responses

Wrapped in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

Create or update the organization dunning policy

PUT

https://api.kontorion.eu/v1

/dunning-policy

Creates a new dunning policy if none exists, or updates the existing one

Create or update the organization dunning policy › Request Body

name

string

object[]

Create or update the organization dunning policy › Responses

Updated policy in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

Get a plan-level dunning policy

GET

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Returns the dunning policy override for a specific plan

Get a plan-level dunning policy › path Parameters

planId

string · required

Plan UUID

Get a plan-level dunning policy › Responses

Wrapped in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string

Create or update a plan-level dunning policy

PUT

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Creates or updates a dunning policy override scoped to a specific plan

Create or update a plan-level dunning policy › path Parameters

planId

string · required

Plan UUID

Create or update a plan-level dunning policy › Request Body

name

string

object[]

Create or update a plan-level dunning policy › Responses

Updated policy in data envelope

created_at

string

deleted_at

string

id

string

is_active

boolean

name

string

organization_id

string

plan_id

string

object[]

updated_at

string