Skip to main content
POST
Write off an invoice (Ausbuchung)
Draft documentation — API not yet rolled out. This endpoint describes the preview contract and may change before release. Sandbox access is provided separately. See access and limitations.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

uuid
string<uuid>
required

UUID of the invoice in this request.

Response

A Mahnservice invoice. Created held: no dunning process exists until POST /invoices/{uuid}/release/ creates one. The debtor is referenced by UUID and must belong to the same company. Company and environment come from the token, never the payload. Submitting is idempotent on the invoice number.

id
string<uuid>
required
read-only
invoice_number
string
required

Your invoice number. POST with the same number within the same company and access mode returns the existing API invoice without applying changed fields. Correct an existing held invoice with PATCH.

Maximum string length: 100
amount
string<decimal>
required

Full invoice amount in the invoice currency, expressed in major units (for example 123.45). API submissions must be greater than zero. Partial reported payments reduce balance while dunning continues over this full amount.

Pattern: ^[0-9]{1,10}(?:\.[0-9]{1,2})?$
due_date
string<date>
required

Invoice payment due date (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not before document_date). The first dunning level is scheduled using this date plus its configured delay; API invoices must still be explicitly released before dunning.

debtor
string<uuid>
required

ID of a Mahnservice debtor belonging to the authenticated company and the token's access mode. Use the Mahnservice debtors endpoints to create or find it.

access_mode
enum<string>
required

Legacy data-isolation mode inherited from the token, not the API host environment. Modern sandbox and production credentials both use production.

Available options:
test,
production
dunning_state
enum<string> | null
required

Current dunning process state. held means an API invoice awaits release; an invoice settled while held reports paid, cancelled, or written_off. Null means a bookkeeping invoice has never been enrolled.

Available options:
held,
pending,
active,
paused,
completed,
paid,
cancelled,
written_off,
inkasso
archived
boolean
required
read-only

Whether the invoice is archived. Archived invoices are not sendable. A held archived invoice cannot be released or corrected; repeating release after a process already exists returns its current state.

has_document
boolean
required
read-only

Whether a usable invoice PDF is stored. A pending, rejected, or failed upload can have a document object while this flag is false.

document
object | null
required

Current invoice-document ingestion summary, or null when no document record exists. If present, it must reach ready before the invoice can be released.

balance
string<decimal>
required
read-only

Remaining invoice amount in the invoice currency: amount minus reported payments, with a minimum of zero. Paid, cancelled and written-off invoices report zero. Dunning fees are not included; partial payments do not reduce the amount used in dunning notices.

Pattern: ^-?\d{0,12}(?:\.\d{0,2})?$
paid_amount
string<decimal>
required
read-only

Sum of all reported payments in the invoice currency. Payments beyond the invoice amount are accepted and counted here; balance never goes below zero.

Pattern: ^-?\d{0,12}(?:\.\d{0,2})?$
overpaid
boolean
required
read-only

True when paid_amount exceeds amount. Over-payment is recorded, not refused; reconcile it in your own system.

created
string<date-time>
required
read-only
updated
string<date-time>
required
read-only
currency
enum<string>
default:EUR

ISO 4217 currency code for the invoice amount and reported balance (EUR, USD, GBP or CHF). Input is normalized to uppercase. Defaults to EUR when omitted during creation. Dunning fees are charged in EUR.

Available options:
EUR,
USD,
GBP,
CHF
document_date
string<date> | null

Issue date of the invoice (YYYY-MM-DD, between 1900-01-01 and ten years ahead, not after due_date), or null if not supplied.

your_reference
string | null

Optional reference supplied by you for the invoice; this is separate from invoice_number, the submission idempotency key. Blank and null are stored and returned as null.

Maximum string length: 255