Skip to content
HALOWERK

Textwerk

dunning letters

Determines the start of default under § 286 BGB from an agreed calendar due date (Abs. 2 Nr. 1), from the expiry of the deadline in an earlier reminder (Abs. 1) or 30 days after due date and receipt of the invoice (Abs. 3; consumers only with the notice in the invoice; end moved by § 193 BGB). Default interest under § 288 BGB (5 or 9 points above the base rate of the Deutsche Bundesbank, table 2002 to 2026 as of 2026-10-30, act/365, split at rate changes), the 40 EUR flat fee for.

POST https://text.halowerk.com/v1/dunning-letters

Inputs

Fields of the published input schema
FieldTypeRequiredDescription
stageintegerYes1 = Zahlungserinnerung, 2 = Mahnung, 3 = letzte Mahnung.
letter_datestringYesDate of the letter (YYYY-MM-DD).
creditorobjectYes
debtorobjectYes
invoiceobjectYes
previous_remindersarrayNoEarlier reminders with their deadlines.
payment_daysintegerNoDays for the new payment deadline (service defaults: 10, 7, 7 by stage).
reminder_feenumberNoActual dunning costs in EUR (postage etc.); only charged when default had begun before the letter.
placestringNoPlace for the date line.
statestringNoGerman federal state whose public holidays apply to the deadline (e.g. NW, BY). Without it only nationwide holidays are used.
Show full input schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "stage",
    "letter_date",
    "creditor",
    "debtor",
    "invoice"
  ],
  "properties": {
    "stage": {
      "type": "integer",
      "enum": [
        1,
        2,
        3
      ],
      "description": "1 = Zahlungserinnerung, 2 = Mahnung, 3 = letzte Mahnung."
    },
    "letter_date": {
      "type": "string",
      "format": "date",
      "description": "Date of the letter (YYYY-MM-DD)."
    },
    "creditor": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "street",
        "postcode",
        "city"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Name or company."
        },
        "addition": {
          "type": "string",
          "maxLength": 120,
          "description": "Optional second address line (department, c/o)."
        },
        "street": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Street and house number."
        },
        "postcode": {
          "type": "string",
          "pattern": "^[0-9A-Z -]{3,10}$",
          "description": "Postcode."
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80,
          "description": "City."
        },
        "country": {
          "type": "string",
          "maxLength": 60,
          "description": "Country, only for addresses abroad."
        },
        "iban": {
          "type": "string",
          "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9 ]{11,36}$",
          "description": "IBAN for the payment."
        },
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 120
        },
        "phone": {
          "type": "string",
          "maxLength": 40
        }
      }
    },
    "debtor": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "street",
        "postcode",
        "city",
        "consumer"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Name or company."
        },
        "addition": {
          "type": "string",
          "maxLength": 120,
          "description": "Optional second address line (department, c/o)."
        },
        "street": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Street and house number."
        },
        "postcode": {
          "type": "string",
          "pattern": "^[0-9A-Z -]{3,10}$",
          "description": "Postcode."
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80,
          "description": "City."
        },
        "country": {
          "type": "string",
          "maxLength": 60,
          "description": "Country, only for addresses abroad."
        },
        "consumer": {
          "type": "boolean",
          "description": "true if the debtor is a consumer (§ 13 BGB); changes interest rate, flat fee and § 286 Abs. 3."
        }
      }
    },
    "invoice": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "number",
        "date",
        "due_date",
        "amount"
      ],
      "properties": {
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "date": {
          "type": "string",
          "format": "date",
          "description": "Invoice date."
        },
        "due_date": {
          "type": "string",
          "format": "date",
          "description": "Due date of the claim."
        },
        "due_date_agreed": {
          "type": "boolean",
          "default": false,
          "description": "true if the due date was agreed in the contract as a calendar date (§ 286 Abs. 2 Nr. 1 BGB); a date only printed on the invoice does not count."
        },
        "received_date": {
          "type": "string",
          "format": "date",
          "description": "Date the debtor received the invoice (for § 286 Abs. 3 BGB)."
        },
        "notice_30_days": {
          "type": "boolean",
          "default": false,
          "description": "Consumers only: the invoice pointed out the 30-day default rule of § 286 Abs. 3 BGB."
        },
        "amount": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 100000000,
          "description": "Gross invoice amount in EUR."
        },
        "paid": {
          "type": "number",
          "minimum": 0,
          "default": 0,
          "description": "Partial payments already received in EUR."
        }
      }
    },
    "previous_reminders": {
      "type": "array",
      "maxItems": 5,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "date",
          "deadline"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "deadline": {
            "type": "string",
            "format": "date",
            "description": "Payment deadline set in that reminder."
          }
        }
      },
      "description": "Earlier reminders with their deadlines."
    },
    "payment_days": {
      "type": "integer",
      "minimum": 5,
      "maximum": 30,
      "description": "Days for the new payment deadline (service defaults: 10, 7, 7 by stage)."
    },
    "reminder_fee": {
      "type": "number",
      "minimum": 0,
      "maximum": 20,
      "description": "Actual dunning costs in EUR (postage etc.); only charged when default had begun before the letter."
    },
    "place": {
      "type": "string",
      "maxLength": 60,
      "description": "Place for the date line."
    },
    "state": {
      "type": "string",
      "enum": [
        "BB",
        "BE",
        "BW",
        "BY",
        "HB",
        "HE",
        "HH",
        "MV",
        "NI",
        "NW",
        "RP",
        "SH",
        "SL",
        "SN",
        "ST",
        "TH"
      ],
      "description": "German federal state whose public holidays apply to the deadline (e.g. NW, BY). Without it only nationwide holidays are used."
    }
  }
}

Open original schema

Published input example

{
  "stage": 2,
  "letter_date": "2026-11-10",
  "creditor": {
    "name": "Beispiel Manufaktur GmbH",
    "street": "Hallenweg 1",
    "postcode": "48599",
    "city": "Gronau",
    "iban": "DE79000000001234567890"
  },
  "debtor": {
    "name": "Kunde AG",
    "street": "Amtsweg 2",
    "postcode": "48143",
    "city": "Münster",
    "consumer": false
  },
  "invoice": {
    "number": "RE-2026-0042",
    "date": "2026-09-15",
    "due_date": "2026-10-01",
    "received_date": "2026-09-16",
    "amount": 1190
  },
  "previous_reminders": [
    {
      "date": "2026-10-05",
      "deadline": "2026-10-15"
    }
  ],
  "state": "NW"
}

Result & documentation

Machine-readable documentation of this hub

Source of this page: the published HALOWERK catalog. Updated: 2026-11-17 UTC.

More endpoints in this hub

All endpoints in this hub →