> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywise.de/llms.txt > Use this file to discover all available pages before exploring further. # Lifecycle and integration rules > Endpoint overview, held invoices, safe retries, document states, and webhook handling for the beta. **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 | Operation | Method and path | | --------------------------------- | ----------------------------------------------------------------------------------------------------- | | Inspect token/company/environment | `GET /info/` | | Create/list debtors | `POST /debtors/`, `GET /debtors/` | | Read debtor | `GET /debtors/{id}/` | | Create/list invoices | `POST /invoices/`, `GET /invoices/` | | Read/correct held invoice | `GET /invoices/{id}/`, `PATCH /invoices/{id}/` | | Release | `POST /invoices/{id}/release/` | | Report/list payments | `POST /invoices/{id}/payments/`, `GET /invoices/{id}/payments/` | | Cancel/write off | `POST /invoices/{id}/cancel/`, `POST /invoices/{id}/write-off/` | | Upload/list document | `POST /invoices/{id}/documents/`, `GET /invoices/{id}/documents/` | | Read/download document | `GET /invoices/{id}/documents/{document_id}/`, `GET /invoices/{id}/documents/{document_id}/download/` | | Read dunning | `GET /invoices/{id}/dunning/` | | Pause/resume | `POST /invoices/{id}/dunning/pause/`, `POST /invoices/{id}/dunning/resume/` | | Read flows | `GET /dunning-flows/`, `GET /dunning-flows/{id}/` | 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. | Status | Integration response | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | | `400` | Correct invalid fields, unsupported parameters, or unexpected bodies. | | `401` / `403` | Check credentials, scopes, company access, subscription and terms. | | `404` | Check resource IDs and the key's company/environment. | | `409` | Fetch current state and resolve the lifecycle conflict; do not retry blindly. | | `429` | Wait according to `Retry-After`. | | `500` / `503` | Retain `X-Paywise-Request-Id` for support and reconcile state before retrying writes; honor `Retry-After` when present. | 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.