List dunning levels

Returns a paginated list of all dunning levels of the company, sorted by internal ID ascending. The id of a dunning level is the value Create dunning notice expects as dunningTypeId — this endpoint returns it even for a company that has never dunned anything: the first call then creates the default dunning levels, so you never get an empty list.

Required license

This endpoint requires the Dunning add-on.

Request

GET /api/oauth/v2/resource/invoices/dunnings/types

Header

Header	Value
Authorization	Bearer {access_token}

Query parameters

Parameter	Type	Required	Description
offset	integer	No	Start position (default: 0)
limit	integer	No	Number of results (default: 50, max: 200)
status	string	No	Filters by status. Allowed values: active, deleted, all. Comma-separated multiple values are supported, default all. See Conventions

Note: The list is sorted by internal ID ascending (see Conventions) — that is not the same as the escalation order. The escalation order of a dunning level is in the sort field; if you need the dunning levels in that order, sort by it client-side. Without a status filter (default all), deleted dunning levels are included too, recognizable by deleted = true.

Required scope: dunnings

The owning user of your API access also needs the Mahnwesen: Anzeigen permission.

Response

Success (200 OK)

{
  "data": [
    {
      "id": "0f6b1c4a-8d21-4b7e-9a33-5c81e2f40a17",
      "name": "1. Mahnung",
      "text": "Dear Sir or Madam, we would like to remind you of the following open invoice.",
      "emailSubject": null,
      "emailBody": null,
      "color": "#f5a623",
      "sort": 1,
      "dunningFee": "5.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 14,
      "tenancies": ["7c2f5b81-40de-4a19-b6c3-8ea1d0742f95"],
      "deleted": false
    },
    {
      "id": "7f8e9d0c-1b2a-3456-789a-bcdef0123456",
      "name": "2. Mahnung",
      "text": "Dear Sir or Madam, despite our first reminder the invoice is still open.",
      "emailSubject": "Payment reminder",
      "emailBody": "Dear Sir or Madam, ...",
      "color": "#d0021b",
      "sort": 2,
      "dunningFee": "12.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 7,
      "tenancies": ["7c2f5b81-40de-4a19-b6c3-8ea1d0742f95", "b3d4e5f6-7890-4a1b-8c2d-3e4f5a6b7c8d"],
      "deleted": false
    }
  ],
  "meta": {
    "total": 3,
    "offset": 0,
    "limit": 50
  }
}

Response fields

Field	Type	Description
data	Array	List of dunning levels
data[].id	string (UUID) | null	Unique ID of the dunning level — this is the value that goes into the create request as dunningTypeId
data[].name	string | null	Name of the dunning level (e.g. 1. Mahnung)
data[].text	string | null	Dunning text as printed on the letter to the customer
data[].emailSubject	string | null	Subject of the reminder email, null = default template
data[].emailBody	string | null	Body of the reminder email, null = default template
data[].color	string | null	Color of the dunning level as a hex code
data[].sort	integer	Position in the escalation order — not the sort order of this endpoint's results, see above
data[].dunningFee	string | null	Dunning fee of this dunning level
data[].latePaymentInterestRate	string | null	Late payment interest rate in percent
data[].paymentDeadline	integer | null	Payment deadline in days
data[].tenancies	Array<string (UUID)>	IDs of the tenancies this dunning level is available for — empty without the Tenancies add-on
data[].deleted	boolean	Whether the dunning level is deleted
meta.total	integer	Total number of dunning levels
meta.offset	integer	Current start position
meta.limit	integer	Requested page size

Note on monetary amounts: dunningFee and latePaymentInterestRate come as a JSON string, not as a number ("dunningFee": "5.00"). Process the values with a decimal type. If you parse them into a floating-point number, you build in rounding errors. Same behavior as with dunning notices, invoices, and cash revenues.

Note: paymentDeadline is a number of days, not a date.

Note on meta.total: Unlike List dunning notices, total is an exact count here. The permission check happens before counting, not after.

Note on tenancies: This field tells you which tenancies a dunning level is available for — not which tenancies it was explicitly assigned to. A dunning level without a tenancy restriction is available everywhere and therefore lists the IDs of all tenancies of your company, not an empty array. If your company works without the Tenancies add-on, every dunning level comes with "tenancies": []. This pays off when creating a dunning notice: Create dunning notice rejects the request with 400 validation_error if the dunning level is not available for the tenancy of the invoice. With tenancies you pick the right dunning level up front instead of finding out by trial and error.

Beispiele

bash

curl -X GET "https://my.offisy.at/api/oauth/v2/resource/invoices/dunnings/types?offset=0&limit=50&status=beispiel" \
  -H "Authorization: Bearer {access_token}"

Server

Client-ID

Client-Secret

Parameter

offset integer

limit integer

status string

Zuerst Token anfordern

Possible errors

Status	Code	Description
400	validation_error	Invalid value for status
401	invalid_client	Access token invalid or expired
403	insufficient_scope	Scope dunnings not present
403	access_denied	No permission to read dunning notices
429	rate_limit_exceeded	Too many requests — see Error Handling

Note: If the Authorization header is missing or the token is invalid, the API answers with 401 and the JSON envelope invalid_client. This holds for the OAuth API in general, not just for this endpoint.