> ## 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. # Get the dunning state > The dunning process of this invoice: state (held until release), pause state, current level, next action date, the dunning flow, and the history of sent dunnings with their fees. ## OpenAPI ````yaml /api-docs/mahnservice-api/openapi.json get /mahnservice/v1/invoices/{uuid}/dunning/ openapi: 3.0.3 info: description: >- Public REST API for the paywise Mahnservice (pre-collection dunning), an alternative input path to the bookkeeping integrations (Lexware Office, sevDesk) and the CSV import. Authentication uses a Bearer token (the same token works for the Inkasso API). Each token is bound to a company and a legacy access mode: `test` or `production`. Access mode is a data-isolation lane, not the API environment: modern credentials use `production` in both production and sandbox. Read `/info/`'s `environment` (`production` or `sandbox`) to identify the environment serving your request. Resources: token introspection (`/info/`), debtors (create/list/get), and the invoice lifecycle -- submit (held), upload the invoice PDF (multipart or base64; scanned asynchronously, poll the document `status`), release for dunning, report payments, cancel / write off, and read the dunning state (`dunning_state`, the dunning flow and the sent dunnings with their fees), pause and resume the dunning, and read the dunning-flow configuration (`/dunning-flows/`). Webhooks notify you about `invoice.created`, `invoice.paid`, `invoice.cancelled`, `invoice.written_off`, `dunning.level_advanced` and `dunning.handed_to_collection`. Test-mode invoices are visible everywhere but never dunned, and their events only reach test-mode endpoints. Contract: requests are JSON only (documents may also be multipart); unknown or read-only body fields and unknown query parameters are rejected with `400`; list pages take `limit` (1-100, default 10) and `offset`. Errors are English and machine-readable: every error body is `{detail, code[, errors]}` -- branch on `code` (`validation_error` with per-field `errors`, `not_authenticated`, `permission_denied` -- the token lacks the scope, `subscription_required` -- no active Mahnservice subscription (writes other than payment reporting), `company_locked` -- the account is locked by paywise (every write), `not_found`, `unsupported_media_type`, `request_too_large`, `throttled`, `unexpected_body`, and the documented `409` codes). A repeat submission of an invoice number that was cancelled, written off or archived is a `409` (`invoice_cancelled` / `invoice_written_off` / `invoice_archived`), not a replay. `HEAD` mirrors `GET` and never writes. Every response carries `X-Paywise-Request-Id`, `X-Paywise-Environment` and `Cache-Control: private, no-store`. Token scopes apply: `mahnservice:debtors:read` / `:write` and `mahnservice:invoices:read` / `:write` (a `:write` grant includes `:read`; keys minted with the full `*` grant have everything). Rate limits: 600 requests per minute per key and per company, shared with the Case Management API, plus a per-operation window of 120 writes per minute; a `429` carries `Retry-After`. title: paywise Mahnservice API version: v1 servers: - description: Production environment url: https://api.paywise.de security: [] tags: - description: The authenticated credential and its context. name: Info - description: Debtors invoices are addressed to. name: Debtors - description: Held invoices, their release, payments and documents. name: Invoices - description: Dunning flow configurations referenced by invoices. name: Dunning flows externalDocs: url: https://docs.paywise.de/api-docs/mahnservice-api/introduction paths: /mahnservice/v1/invoices/{uuid}/dunning/: get: tags: - Invoices summary: Get the dunning state description: >- The dunning process of this invoice: state (held until release), pause state, current level, next action date, the dunning flow, and the history of sent dunnings with their fees. operationId: get-invoice-dunning parameters: - description: UUID of the invoice in this request. in: path name: uuid required: true schema: format: uuid type: string responses: '200': content: application/json: examples: active: summary: Released; dunning process active value: current_level: 1 dunning_flow: id: 73000000-0000-4000-8000-000000000001 level_count: 3 levels: 3 name: Standard reminders dunnings: [] next_action_date: '2026-09-04T00:00:00+02:00' pause_reason: null paused_at: null state: active held: summary: Submitted; awaiting explicit release value: current_level: null dunning_flow: null dunnings: [] next_action_date: null pause_reason: null paused_at: null state: held paused: summary: Dunning process paused value: current_level: 1 dunning_flow: id: 73000000-0000-4000-8000-000000000001 level_count: 3 levels: 3 name: Standard reminders dunnings: [] next_action_date: '2026-09-04T00:00:00+02:00' pause_reason: user paused_at: '2026-09-03T09:00:00Z' state: paused pending: summary: Released; awaiting dunning-flow activation value: current_level: 1 dunning_flow: id: 73000000-0000-4000-8000-000000000001 level_count: 3 levels: 3 name: Standard reminders dunnings: [] next_action_date: '2026-09-04T00:00:00+02:00' pause_reason: null paused_at: null state: pending schema: $ref: '#/components/schemas/DunningState' description: '' headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '429': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string Retry-After: description: Integer seconds to wait before retrying a throttled request. schema: minimum: 1 type: integer X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Standard error response. headers: Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: format: uuid type: string security: - tokenAuth: [] components: schemas: DunningState: description: |- The dunning state of one invoice: the dunning process plus the history of sent notices. A held, never-released invoice reports the held shape with no process. properties: current_level: description: >- One-based next dunning level. It can be one beyond the final configured level after the last notice; null when no dunning process exists. nullable: true readOnly: true type: integer dunning_flow: allOf: - $ref: '#/components/schemas/DunningFlowSummary' description: >- Flow assigned to this invoice's dunning process, which can be an older configuration version. Null when no process or assigned flow exists. nullable: true readOnly: true dunnings: description: >- History of sent or attempted dunning notices. Empty when the invoice has no dunning process. items: $ref: '#/components/schemas/Dunning' readOnly: true type: array next_action_date: description: >- Scheduled time of the next dunning action, which can be a notice or automatic debt-collection handover. Null when no action is scheduled or no process exists. format: date-time nullable: true readOnly: true type: string pause_reason: allOf: - $ref: '#/components/schemas/PauseReasonEnum' description: >- Reason recorded for the process hold (manual user pause, subscription, administrator, debtor hold, or disconnected integration); null when no reason is recorded. nullable: true readOnly: true paused_at: description: >- Time the process entered its current pause. Null when not paused, when no process exists, or when a legacy pause has no recorded timestamp. format: date-time nullable: true readOnly: true type: string state: allOf: - $ref: '#/components/schemas/MahnserviceDunningStateEnum' description: >- 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. nullable: true readOnly: true required: - current_level - dunning_flow - dunnings - next_action_date - pause_reason - paused_at - state type: object Error: properties: code: description: Machine-readable error category. type: string detail: description: Short human-readable summary of the error. type: string errors: description: Field-level validation errors, when applicable. items: $ref: '#/components/schemas/ErrorItem' type: array required: - detail - code type: object DunningFlowSummary: description: |- The flow the process runs on (summary; the full config lives at GET /dunning-flows/). Fixed shape, not a free-form dict, so SDK generators get real types. properties: id: description: Stable identifier of the dunning flow. format: uuid readOnly: true type: string level_count: description: Number of configured dunning levels. readOnly: true type: integer levels: description: >- Number of levels (same value as level_count; kept for compatibility). readOnly: true type: integer name: description: Name of the dunning flow. readOnly: true type: string required: - id - level_count - levels - name type: object Dunning: description: One sent (or attempted) dunning notice. properties: channel: allOf: - $ref: '#/components/schemas/ChannelEnum' description: 'Delivery channel for this notice: email, postal letter, or both.' readOnly: true dunning_fee: allOf: - $ref: '#/components/schemas/DunningFee' description: >- Fee charged with this notice, recorded at send time; null if no fee was charged. Later flow changes do not change this historical amount. nullable: true readOnly: true error_message: description: >- Public explanation of the notice's delivery error, or null when no error is recorded. nullable: true readOnly: true type: string level: description: One-based dunning level for this sent or attempted notice. readOnly: true type: integer sent_at: description: Time the notice was sent; null if no send time is recorded. format: date-time nullable: true readOnly: true type: string state: allOf: - $ref: '#/components/schemas/MahnserviceMahnungStatusEnum' description: >- Delivery state of this individual notice, separate from the invoice's dunning process state. manual means manual sending is required. readOnly: true required: - channel - dunning_fee - error_message - level - sent_at - state type: object PauseReasonEnum: description: |- * `user` - Manuell pausiert * `subscription` - Abo gekündigt * `admin` - Vom Administrator pausiert * `debtor` - Schuldner pausiert * `integration` - Buchhaltungs-Verbindung getrennt enum: - user - subscription - admin - debtor - integration type: string MahnserviceDunningStateEnum: description: |- * `held` - Held * `pending` - Pending * `active` - Aktiv * `paused` - Pausiert * `completed` - Abgeschlossen * `paid` - Paid * `cancelled` - Storniert * `written_off` - Ausgebucht * `inkasso` - An Inkasso übergeben enum: - held - pending - active - paused - completed - paid - cancelled - written_off - inkasso type: string ErrorItem: properties: code: description: Machine-readable field error code. type: string field: description: >- Path to the field that caused the error, using dots for objects and brackets for list indexes, for example `claims[0].amount`; null for an error without a field path. nullable: true type: string message: description: Human-readable explanation of the field error. type: string required: - field - code - message type: object ChannelEnum: description: |- * `email` - E-Mail * `letter` - Brief * `both` - E-Mail & Brief enum: - email - letter - both type: string DunningFee: description: The Mahngebühr charged with a sent Mahnung (snapshotted at send time). properties: amount: description: Dunning fee in EUR, recorded at send time. format: decimal pattern: ^-?\d{0,6}(?:\.\d{0,2})?$ readOnly: true type: string charged_at: description: Time at which the dunning fee was charged. format: date-time readOnly: true type: string required: - amount - charged_at type: object MahnserviceMahnungStatusEnum: description: |- * `pending` - Pending * `sent` - Versendet * `delivered` - Zugestellt * `opened` - Geöffnet * `bounced` - Unzustellbar * `failed` - Fehlgeschlagen * `manual` - Manuell versenden enum: - pending - sent - delivered - opened - bounced - failed - manual type: string securitySchemes: tokenAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.