List dunning notices

Returns a paginated list of all dunning notices of the company, sorted by internal ID ascending.

Required license

This endpoint requires the Dunning add-on.

Request

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

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, replaced, canceled, all. Comma-separated multiple values are supported, default all. See Conventions
dunningStatus	string	No	Filters by the business dunning status. Allowed values: active, replaced, canceled, done
paidStatus	string	No	Filters by payment status. Allowed values: open, paid

Required scope: dunnings

Note: An empty value (?status= or ?dunningStatus=) acts like no filter — the API returns the unfiltered list. An invalid value is rejected with 400 validation_error. status and dunningStatus are two different filters and are AND-combined: status is the technical soft-delete status from the Conventions, dunningStatus is the business escalation status.

Response

Success (200 OK)

{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
      "invoice": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "customer": "f0e1d2c3-b4a5-6789-fedc-ba9876543210",
      "status": "active",
      "text": "Dear Sir or Madam, we would like to remind you of the following open invoice.",
      "printedStatus": "unprinted",
      "paidStatus": "open",
      "dunningType": "7f8e9d0c-1b2a-3456-789a-bcdef0123456",
      "fee": "12.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 14,
      "totalAmount": "122.35",
      "outstandingTotal": "122.35",
      "totalFee": "12.00",
      "outstandingFee": "12.00",
      "totalInterest": "0.35",
      "outstandingInterest": "0.35",
      "invoiceOutstandingBalance": "110.00",
      "interestCalculateStartDate": "2026-06-16",
      "interestCalculateEndDate": "2026-07-15",
      "createdAt": "2026-07-15T09:00:00+02:00",
      "updatedAt": "2026-07-15T09:00:00+02:00",
      "createdBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "updatedBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "tenancy": "9a8b7c6d-5e4f-3210-9876-543210fedcba"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-345678901234",
      "invoice": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "customer": null,
      "status": "replaced",
      "text": "Dear Sir or Madam, despite our first reminder the invoice is still open.",
      "printedStatus": "printed",
      "paidStatus": "open",
      "dunningType": "0f6b1c4a-8d21-4b7e-9a33-5c81e2f40a17",
      "fee": "5.00",
      "latePaymentInterestRate": "4.00",
      "paymentDeadline": 7,
      "totalAmount": "55.00",
      "outstandingTotal": "55.00",
      "totalFee": "5.00",
      "outstandingFee": "5.00",
      "totalInterest": "0.00",
      "outstandingInterest": "0.00",
      "invoiceOutstandingBalance": "50.00",
      "interestCalculateStartDate": null,
      "interestCalculateEndDate": null,
      "createdAt": "2026-06-30T08:15:00+02:00",
      "updatedAt": "2026-07-15T09:00:00+02:00",
      "createdBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "updatedBy": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "tenancy": null
    }
  ],
  "meta": {
    "total": 37,
    "offset": 0,
    "limit": 50
  }
}

Response fields

Field	Type	Description
data	Array	List of dunning notices
data[].id	string (UUID) | null	Unique ID of the dunning notice
data[].invoice	string (UUID) | null	ID of the dunned invoice, loadable via Get Invoice
data[].customer	string (UUID) | null	ID of the customer, loadable via Get Customer
data[].status	string	Technical status: active, replaced, canceled. See Conventions
data[].text	string | null	Dunning text as printed on the letter to the customer
data[].printedStatus	string	Print status: printed, unprinted
data[].paidStatus	string	Payment status: open, paid
data[].dunningType	string (UUID) | null	ID of the dunning level, loadable via Get dunning level
data[].fee	string	Dunning fee of this dunning level
data[].latePaymentInterestRate	string	Late payment interest rate in percent
data[].paymentDeadline	integer	Payment deadline in days
data[].totalAmount	string	Total amount of the dunning notice
data[].outstandingTotal	string	Outstanding total amount
data[].totalFee	string	Total dunning fees
data[].outstandingFee	string	Outstanding dunning fees
data[].totalInterest	string	Total late payment interest
data[].outstandingInterest	string	Outstanding late payment interest
data[].invoiceOutstandingBalance	string	Outstanding amount of the dunned invoice
data[].interestCalculateStartDate	string | null	Start of interest calculation (YYYY-MM-DD)
data[].interestCalculateEndDate	string | null	End of interest calculation (YYYY-MM-DD)
data[].createdAt	string (ISO 8601)	Creation timestamp
data[].updatedAt	string (ISO 8601)	Last change timestamp
data[].createdBy	string (UUID) | null	ID of the user who created the dunning notice, loadable via Get User
data[].updatedBy	string (UUID) | null	ID of the user who made the last change
data[].deleted	boolean	Whether the dunning notice is deleted
data[].deletedAt	string (ISO 8601) | null	Deletion timestamp
data[].deletedBy	string (UUID) | null	ID of the user who deleted the dunning notice
data[].tenancy	string (UUID) | null	ID of the assigned tenancy
meta.total	integer	Upper bound of the total count — see note below
meta.offset	integer	Current start position
meta.limit	integer	Number of returned entries

Note on monetary amounts: All monetary amounts and the interest rate come as a JSON string, not as a number ("fee": "12.00"). This affects fee, latePaymentInterestRate, totalAmount, outstandingTotal, totalFee, outstandingFee, totalInterest, outstandingInterest, and invoiceOutstandingBalance. 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 invoices and cash revenues.

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

Note on meta.total: total is counted in the database, the permission check happens afterwards. The value is therefore an upper bound, not an exact count — the pages may contain fewer dunning notices than total suggests. A stop condition of "paginate until all total records are received" does not terminate. Paginate until a page is empty instead.

This matters most with restricted permissions: if the owning user of your API access is restricted to locations, dunning notices without a location assignment are invisible to them.

Note on tenancies: If your company works with the Tenancies add-on, the endpoint returns only dunning notices from tenancies the owning user of your API access has access to and where they hold the Mahnwesen: Anzeigen permission. Dunning notices of other tenancies and dunning notices without a tenancy are missing from the list without triggering an error. meta.total counts only the dunning notices of those tenancies. Details: Conventions.

Note on cancellation: A cancellation sets dunningStatus = canceled and the soft-delete flag at the same time. Without a status filter (default all) you get canceled and deleted dunning notices back, recognizable by status = canceled or deleted = true. To exclude them, filter with status=active,replaced.

Beispiele

bash

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

Server

Client-ID

Client-Secret

Parameter

offset integer

limit integer

status string

dunningStatus string

paidStatus string

Zuerst Token anfordern

Possible errors

Status	Code	Description
400	validation_error	Invalid value for status, dunningStatus, or paidStatus
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.