Skip to main content
Draft documentation — API not yet rolled out. These documents are published in advance so you can prepare your integration. The contract and examples may change before release. Sandbox access will be provided separately; publication of these documents does not mean the API is available for testing or production use.
All paths below are relative to the supplied API origin plus /mahnservice/v1/. Keep the trailing slash. All business operations require a Bearer key with the corresponding scopes.

​
Endpoint overview

Top-level lists accept limit (1–100, default 10) and offset. Payment/document lists and the dunning sub-resource are not paginated. Unknown query parameters are rejected: do not assume invoice status/date filters are supported.

​
Held, released, and settled invoices

Creating an invoice stores it without starting a dunning process. While it is held, PATCH can correct invoice_number, amount, currency, due_date, document_date, your_reference, and debtor, subject to state/payment restrictions. Once payments exist, currency changes are refused. Once released, invoice correction and document replacement are refused. Release, pause, resume, cancel and write-off take no request body. Do not send {}. Pause/resume obey company/debtor restrictions; they cannot override administrative locks. No hard-delete operation is provided. Only API-sourced invoices can be mutated through this API. Reading bookkeeping-imported invoices does not grant permission to modify them here. Full payment before handover stops dunning. Partial payments reduce balance, but the current process continues over the full invoice amount. Once handed to Inkasso, cancel/write-off return 409 invoice_in_inkasso. Collection settlement is not written back into the Mahnservice process state. Ask paywise about withdrawing a collection case.

​
Retries and duplicates

  • Invoice creation: deduplicated by company, invoice number, source and legacy access mode. A repeated valid request returns the existing invoice with 200, ignoring changed field values. Cancelled, written-off or archived invoices return a conflict instead. Changing the invoice number via PATCH changes the deduplication identity.
  • Debtor creation: not idempotent. Persist the returned UUID and serialize creation for each customer. GET /debtors/?customer_number=... matches exactly and case-sensitively; email matches exactly and case-insensitively. Combined filters use AND. Multiple matches are possible.
  • Payments: an identical amount/date/reference can replay the existing payment. An identical payment without a reference returns 409 duplicate_payment; do not invent a new reference just to bypass it.
  • This API does not implement generic Idempotency-Key handling. Do not assume that header protects a request.

​
Documents

Supply multipart file or JSON base64, with optional JSON filename. Only PDF bytes are supported; URLs are not. A document is optional, but once supplied it must reach ready before release. Download is available only for ready documents. Multiple PDFs per invoice are planned for a later contract update. Do not implement repeated uploads as an append operation against this preview. A new upload replaces the single attachment while held. Failed/rejected documents require new bytes. A failed replacement does not restore the earlier attachment, and terminal failures discard the quarantined bytes. The shared scanner’s deployment configuration determines whether antivirus scanning is required. A ready document must not be interpreted as proof of an antivirus scan when scanning is not enabled. Confirm the beta environment’s scanner configuration with paywise.

​
Errors and throttling

Errors use detail and a machine-readable code, with optional field-level errors. Handle codes instead of matching English text. Token and company budgets are each 600 requests/minute, shared with Case API v2. Endpoint budgets distinguish reads (600/minute) and writes (120/minute). Use bounded retries and backoff.

​
Webhooks

The beta event set is:
  • invoice.created
  • invoice.paid
  • invoice.cancelled
  • invoice.written_off
  • dunning.level_advanced
  • dunning.handed_to_collection
These events use the shared webhook infrastructure, not a Mahnservice /webhooks/ endpoint. Coordinate subscription setup for the beta with paywise. The v2 event data contains company_id, invoice_id, and invoice_url; retrieve the invoice and its dunning resource for current state. Do not expect full invoice details or an Inkasso claim ID in the event. Consumers should tolerate duplicate and delayed delivery. Failed sends and paused processes do not have dedicated events; query the current state for those cases. API-submitted and bookkeeping-imported invoices can both emit invoice events.