Create dunning notice

Creates a new dunning notice for an open invoice.

Required license

This endpoint requires the Dunning add-on.

Request

POST /api/oauth/v2/resource/invoices/dunnings

Header

Header	Value
Authorization	Bearer {access_token}
Content-Type	application/json

Body parameters

Field	Type	Required	Description
invoiceId	string (UUID)	Yes	Invoice the dunning notice belongs to
dunningTypeId	string (UUID)	Yes	Dunning level the values are taken from
interestCalculateStartDate	string	No	Start of interest calculation (YYYY-MM-DD)
interestCalculateEndDate	string	No	End of interest calculation (YYYY-MM-DD)

Note: The endpoint does not accept the dunning fee, the late payment interest rate, the payment deadline, or the dunning text — these values come exclusively from the selected dunning level. This is intentional: no external system decides which amounts are charged to a customer or how a letter to them is worded. If you need different values, change the dunning level in Offisy or pick a different one. totalFee reports the cumulative amount: the dunning fees of all previous notices for the same invoice are added up.

Note: interestCalculateStartDate and interestCalculateEndDate only apply together — if you set just one of them, the endpoint answers with 400 validation_error. Send both dates in YYYY-MM-DD format with a two-digit month and day, as a real calendar date; the interest start must not be after the interest end. If you omit both, Offisy suggests the same period as the interface does: 14 days, starting the day after the invoice due date — this is a prefill that can change.

Note: List dunning levels returns the UUID of a dunning level — the id field of a dunning level is the value you send here as dunningTypeId. That endpoint also works for a company that has never dunned anything.

Required scope: dunnings

The owning user of your API access also needs the Mahnwesen: Erstellen permission and access to the invoice and the dunning level.

Example (cURL)

curl -X POST "https://app.offisy.at/api/oauth/v2/resource/invoices/dunnings" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "dunningTypeId": "7f8e9d0c-1b2a-3456-789a-bcdef0123456",
    "interestCalculateStartDate": "2026-06-16",
    "interestCalculateEndDate": "2026-07-15"
  }'

Response

Success (201 Created)

{
  "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"
  }
}

Response fields

The endpoint returns the same object as the two read endpoints. See Get dunning notice for the full field description.

Beispiele

bash

curl -X POST "https://my.offisy.at/api/oauth/v2/resource/invoices/dunnings" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "dunningTypeId": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
    "interestCalculateStartDate": "2026-04-15T10:00:00",
    "interestCalculateEndDate": "2026-04-15T10:00:00"
  }'

Server

Client-ID

Client-Secret

Parameter

invoiceId *string

dunningTypeId *string

interestCalculateStartDate string

interestCalculateEndDate string

Zuerst Token anfordern

Possible errors

Status	Code	Description
400	validation_error	invoiceId or dunningTypeId is missing, is not a valid UUID, only one of the two interest dates is set, an interest date is not a real calendar date in YYYY-MM-DD format, or the interest start is after the interest end
400	validation_error	Dunning level belongs to a different company than the invoice — a dunning notice may only use dunning levels of its own company (error_description: dunningTypeId must belong to the same company as the invoice.)
400	validation_error	Dunning level is not available for the tenancy of the invoice — the tenancies field in List dunning levels shows which tenancies a dunning level allows (error_description: dunningTypeId must be available for the tenancy of the invoice.)
400	invalid_request	The API access is not assigned to a user — assign a user to it in the Offisy settings
401	invalid_client	Access token invalid or expired
403	insufficient_scope	Scope dunnings not present
403	access_denied	The owning user of your API access has no permission for the invoice or the dunning level (default error_description: Insufficient permission for this resource.)
404	not_found	Invoice or dunning level not found, or the invoice belongs to a tenancy the owning user of your API access does not have access to or where they lack the Mahnwesen: Erstellen permission under the Tenancies add-on. For the invoice, the response is the same as for an unknown invoice (error_description: Invoice not found.)
422	unprocessable_entity	Invoice cannot be dunned: draft, canceled, storno invoice or an invoice that has been stornoed, cash receipt, training invoice, or no outstanding balance
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.