# Offenen Mahnungsentwurf ändern (https://developer.bimetrics.de/reference/receivables/update-reminder)

`PUT https://app.bimetrics.de/api/reminder/{id}`

operationId: `updateReminder` · Berechtigung (Scope): `invoices:draft` · Bereich: Forderungen und Mahnungen

Speichert die vollständigen bearbeitbaren Felder mit expectedUpdatedAt. Ohne chargeFee, chargeInterest und chargeFlatRate bleibt die gespeicherte Wahl. Ausgestellte oder zurückgezogene Mahnungen bleiben unverändert.

Benötigt einen Schlüssel mit der Berechtigung `invoices:draft`.

> **Achtung:** Ändert Daten der Firma; wird atomar mit Idempotenzbeleg und Herkunft protokolliert.
>
> KI-Agenten fragen vor diesem Aufruf beim Nutzer nach.

### Authentifizierung

`Authorization: Bearer bm_…` (alternativ `X-API-KEY: bm_…`, nie beide zugleich).

### Parameter

| Name | Ort | Pflicht | Typ | Beschreibung |
| --- | --- | --- | --- | --- |
| `id` | path | ja | string (uuid) | ID des Objekts dieser Firma (UUID); bei Forderungsständen und neuen Korrekturen die Quellentwurfs-ID. |
| `Idempotency-Key` | header | ja | string | Stabiler Schlüssel für genau diese Änderung: 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bei Wiederholungen denselben Schlüssel und unveränderten Inhalt senden; das Ergebnis wird nicht nochmals erzeugt. |

### Request-Body (`application/json`)

 

Schema `UpdateReminder`.

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `chargeFee` | boolean | false lässt die Mahngebühr der Stufe auf dieser Mahnung weg. true oder ohne Angabe: Vorschlag übernehmen; bei einer Änderung ohne Angabe bleibt die gespeicherte Wahl. |
| `chargeFlatRate` | boolean | false lässt die Pauschale auf dieser Mahnung weg, sonst wie chargeFee. |
| `chargeInterest` | boolean | false lässt die Verzugszinsen auf dieser Mahnung weg, sonst wie chargeFee. |
| `expectedUpdatedAt` | string (date-time), kann null sein | Exakter zuletzt gelesener updatedAt-Wert des Mahnungsentwurfs. |
| `issueDate` | NaiveDate | Ausstellungsdatum. |
| `kind` | string | payment_reminder für Zahlungserinnerung oder dunning für Mahnung. Ohne level ist payment_reminder Stufe 0 und dunning die nächste Mahnung; mit level muss es dazu passen. |
| `layoutId` | string | Dokumentlayout modern oder classic, am besten weglassen: Eine neue Mahnung übernimmt dann das Layout, das gerade gilt, eine Änderung behält ihres. Sobald Layouts im Layout-Editor gewählt werden, antwortet bimetrics auf jeden anderen Wert mit 400 und dem Code layout_choice_moved. |
| `level` | integer | Stufe: 0 Zahlungserinnerung, 1 bis 3 Mahnung; bestimmt den Titel auf dem PDF, zum Beispiel 2. Mahnung. Ohne Angabe nimmt eine neue Mahnung die nächste Stufe der Rechnung, eine Änderung behält ihre. |
| `paymentDeadline` | NaiveDate | Zahlungsfrist nach dem Ausstellungsdatum. Ohne Angabe nimmt eine neue Mahnung die Frist ihrer Stufe, bei einer Änderung ist sie Pflicht. |
| `text` | string | Text im Dokument, ohne Versandwirkung. Ohne Angabe nimmt eine neue Mahnung den Text ihrer Stufe, bei einer Änderung ist er Pflicht. Platzhalter wie {Frist} füllt das PDF aus, siehe getReminderSettings. |

### Beispiel

```sh
curl --fail-with-body "https://app.bimetrics.de/api/reminder/{id}" \
  -H "Authorization: Bearer $BIMETRICS_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"kind":"and","children":[],"limit":50,"offset":0}'
```

### Antworten

| Status | Beschreibung | Inhalt |
| --- | --- | --- |
| 200 | Erfolg. | `application/json`: PaymentReminder |
| 400 | Ungültige Anfrage, z. B. ein Parameter mit ungültigem Wert wie eine ID, die keine UUID ist; korrigieren statt wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |
| 401 | Kein gültiger Schlüssel: fehlt (`Unauthorized`), ist unbekannt, abgelaufen oder widerrufen oder wurde nicht in genau einem Header gesendet (`InvalidAPIKey`). Schlüssel prüfen, nicht wiederholen. Auch eine ID, die zu einer anderen Firma gehört, ergibt `401 Unauthorized`. | `application/json`: Error |
| 403 | Dem Schlüssel fehlt die Berechtigung für diese Route (`APIKeyPermissionDenied`), oder die Firma hat keinen API-Zugang (mehr), etwa nach Ende der Testphase oder des Abos (`APIUnavailable`). | `application/json`: Error |
| 404 | Nicht gefunden (`NotFound`). | `application/json`: Error |
| 409 | Versionskonflikt (`VersionConflict`), abweichender Inhalt für denselben Idempotency-Key (`IdempotencyConflict`), Dublette (`ContactDuplicate`) oder fachlich gesperrte Änderung. Aktuellen Zustand laden und prüfen; keinen anderen Schlüssel verwenden, um einen Konflikt zu umgehen. | `application/json`: Error |
| 413 | Die Anfrage ist zu groß (`APIRequestTooLarge`), siehe `x-bimetrics-limits`. | `application/json`: Error |
| 422 | Für einen Zinstag fehlt der Basiszinssatz in bimetrics (`ReminderBaseRateMissing`). Die Mahnung bleibt unverändert. Zinsen dieser Mahnung mit `chargeInterest: false` abwählen oder nach der Aktualisierung erneut senden. | `application/json`: Error |
| 429 | Zu viele Anfragen; nach `Retry-After` Sekunden erneut senden. Mehr unter [Fehler](https://developer.bimetrics.de/errors). (Header: Retry-After) | `application/json`: Error |
| 500 | Serverfehler; die Anfrage später wiederholen. Mehr unter [Fehler](https://developer.bimetrics.de/errors). | `application/json`: Error |

#### Felder der Antwort 200 (`PaymentReminder`)

| Feld | Typ | Beschreibung |
| --- | --- | --- |
| `chargeFee` | boolean, kann null sein | Gespeicherte Wahl zur Mahngebühr: false abgewählt, null oder true Vorschlag. |
| `chargeFlatRate` | boolean, kann null sein | Gespeicherte Wahl zur Pauschale, wie chargeFee. |
| `chargeInterest` | boolean, kann null sein | Gespeicherte Wahl zu den Verzugszinsen, wie chargeFee. |
| `charges` | ReminderCharges | Mahngebühr, Verzugszinsen und Pauschale. Beim einzeln gelesenen Entwurf aktuell gerechnet, nach dem Ausstellen eingefroren; null bei Entwürfen in Listen, bei älteren Mahnungen und solange die Rechnung nicht mahnbar ist. |
| `companyId` | string (uuid) | ID der Firma. |
| `createdAt` | string (date-time) | Anlage in bimetrics. |
| `customerName` | string | Empfänger der Originalrechnung. |
| `documentMail` | DocumentMailSummary | Nur in den Antworten von `getReminder` und `listReminders`. Die neueste Mail, mit der diese Mahnung über bimetrics gesendet wurde (aus der App, per API oder per MCP), samt Versandstand. Fehlt, wenn noch keine gesendet wurde. Einen von Hand eingetragenen Versand nennt `externalSentOn`. |
| `externalSentChannel` | string | Dokumentierter externer Weg email, post oder other. |
| `externalSentOn` | NaiveDate | Manuell dokumentiertes externes Versanddatum; kein automatischer Versand. |
| `id` | string (uuid) | ID der Mahnung oder ihres Entwurfs. |
| `issueDate` | NaiveDate | Ausstellungsdatum. |
| `kind` | string | payment_reminder für Zahlungserinnerung oder dunning für Mahnung. |
| `layoutId` | string | Dokumentlayout modern oder classic. |
| `level` | integer | Stufe: 0 Zahlungserinnerung, 1 bis 3 Mahnung. |
| `number` | string | Mahnungsnummer; bei offenem Entwurf leer. |
| `paymentDeadline` | NaiveDate | Zahlungsfrist nach dem Ausstellungsdatum. |
| `printFingerprint` | string | Fingerprint des bei Ausstellung verwendeten Druckstands. |
| `snapshot` | InvoiceReceivable | Bei Ausstellung eingefrorener Forderungsstand. |
| `sourceDocumentId` | string (uuid) | Ausgestellter Originalbeleg. |
| `sourceDraftId` | string (uuid) | Originalrechnungsentwurf. |
| `sourceInvoiceNumber` | string | Nummer der Originalrechnung. |
| `status` | string | draft, issued oder withdrawn. |
| `text` | string | Text im Dokument. Bei Entwürfen mit Platzhaltern, nach dem Ausstellen wie auf dem PDF. |
| `updatedAt` | string (date-time) | Letzte Änderung. |
| `withdrawnAt` | string (date-time) | Zeitpunkt des Zurückziehens; Original und Verlauf bleiben erhalten. |

Verschachtelte Schemas stehen vollständig in der OpenAPI-Beschreibung: https://app.bimetrics.de/api/openapi.json
