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 › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

Get the organization dunning policy › Responses

object · required

Create or update the organization dunning policy

PUT

https://api.kontorion.eu/v1

/dunning-policy

Creates a new dunning policy if none exists (201), or updates the existing one (200).

Create or update the organization dunning policy › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Create or update the organization dunning policy › Request Body

name

string

array | null

Create or update the organization dunning policy › Responses

object · required

PUT/dunning-policy

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

shell

Example Request Body

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

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_active": true,
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "steps": [
      {
        "action": "action",
        "days_after_due": 0,
        "email_event": "email_event"
      }
    ],
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a plan-level dunning policy › Responses

object · required

Create or update a plan-level dunning policy

PUT

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Creates (201) or updates (200) 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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

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

name

string

array | null

Create or update a plan-level dunning policy › Responses

object · required

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": "action",
      "days_after_due": 0,
      "email_event": "email_event"
    }
  ]
}
'

shell

Example Request Body

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

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_active": true,
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "steps": [
      {
        "action": "action",
        "days_after_due": 0,
        "email_event": "email_event"
      }
    ],
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a plan-level dunning policy › Responses

No Content

No data returned

Scheduled Changes Webhook Secrets

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the organization dunning policy › Responses

object · required

Create or update the organization dunning policy

PUT

https://api.kontorion.eu/v1

/dunning-policy

Creates a new dunning policy if none exists (201), or updates the existing one (200).

Create or update the organization dunning policy › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Create or update the organization dunning policy › Request Body

name

string

array | null

Create or update the organization dunning policy › Responses

object · required

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a plan-level dunning policy › Responses

object · required

Create or update a plan-level dunning policy

PUT

https://api.kontorion.eu/v1

/plans/{planId}/dunning-policy

Creates (201) or updates (200) 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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

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

name

string

array | null

Create or update a plan-level dunning policy › Responses

object · required

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 › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a plan-level dunning policy › Responses

No Content

No data returned