> ## 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 an invoice > Invoices for the public Mahnservice API: the full lifecycle. Submit creates a *held* invoice -- no dunning process exists until /release creates one. Release enrolls the invoice into the dunning flow (active when the company's Mahnlauf is activated, pending until then; parked paused under company or debtor holds). PATCH corrects an invoice while it is still held -- the only correction window there is, because submit is idempotent on the invoice number and ignores changed fields, and after release the dunning history already references the amount and the due date. Payments, cancel and write-off settle or end the claim. All scoped to the token's company; the debtor is referenced by UUID. Write actions apply only to API-submitted invoices; bookkeeping-synced invoices are readable here but owned by their bookkeeping system. Payment reporting stays open through a subscription lapse -- a lapsed customer must still be able to stop dunning on a paid invoice. ## OpenAPI ````yaml /api-docs/mahnservice-api/openapi.json get /mahnservice/v1/invoices/{uuid}/ 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}/: get: tags: - Invoices summary: Get an invoice description: >- Invoices for the public Mahnservice API: the full lifecycle. Submit creates a *held* invoice -- no dunning process exists until /release creates one. Release enrolls the invoice into the dunning flow (active when the company's Mahnlauf is activated, pending until then; parked paused under company or debtor holds). PATCH corrects an invoice while it is still held -- the only correction window there is, because submit is idempotent on the invoice number and ignores changed fields, and after release the dunning history already references the amount and the due date. Payments, cancel and write-off settle or end the claim. All scoped to the token's company; the debtor is referenced by UUID. Write actions apply only to API-submitted invoices; bookkeeping-synced invoices are readable here but owned by their bookkeeping system. Payment reporting stays open through a subscription lapse -- a lapsed customer must still be able to stop dunning on a paid invoice. operationId: get-invoice 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: access_mode: production amount: '250.00' archived: false balance: '250.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: active has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 cancelled: summary: Cancelled value: access_mode: production amount: '250.00' archived: false balance: '0.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: cancelled has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 completed: summary: Dunning ladder completed with an outstanding balance value: access_mode: production amount: '250.00' archived: false balance: '250.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: completed has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 held: summary: Submitted; awaiting explicit release value: access_mode: production amount: '250.00' archived: false balance: '250.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: held has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-02T08:00:00Z' your_reference: CUSTOMER-1042 inkasso: summary: Covered by debt collection value: access_mode: production amount: '250.00' archived: false balance: '250.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: inkasso has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 paid: summary: Fully paid value: access_mode: production amount: '250.00' archived: false balance: '0.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: paid has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '250.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 paused: summary: Dunning process paused value: access_mode: production amount: '250.00' archived: false balance: '250.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: paused has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 pending: summary: Released; awaiting dunning-flow activation value: access_mode: production amount: '250.00' archived: false balance: '250.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: pending has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 written_off: summary: Written off value: access_mode: production amount: '250.00' archived: false balance: '0.00' created: '2026-09-02T08:00:00Z' currency: EUR debtor: 72000000-0000-4000-8000-000000000001 document: null document_date: '2026-08-18' due_date: '2026-09-01' dunning_state: written_off has_document: false id: 71000000-0000-4000-8000-000000000001 invoice_number: INV-2026-1042 overpaid: false paid_amount: '0.00' updated: '2026-09-03T09:00:00Z' your_reference: CUSTOMER-1042 schema: $ref: '#/components/schemas/Invoice' 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: Invoice: description: >- 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. properties: access_mode: allOf: - $ref: '#/components/schemas/AccessModeEnum' description: >- Legacy data-isolation mode inherited from the token, not the API host environment. Modern sandbox and production credentials both use production. readOnly: true amount: description: >- 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. format: decimal pattern: ^[0-9]{1,10}(?:\.[0-9]{1,2})?$ type: string archived: description: >- 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. readOnly: true type: boolean balance: description: >- 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. format: decimal pattern: ^-?\d{0,12}(?:\.\d{0,2})?$ readOnly: true type: string created: description: Time at which the invoice was created. format: date-time readOnly: true type: string currency: allOf: - $ref: '#/components/schemas/CurrencyEnum' default: EUR description: >- 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. debtor: description: >- 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. format: uuid type: string document: allOf: - $ref: '#/components/schemas/DocumentSummary' description: >- Current invoice-document ingestion summary, or null when no document record exists. If present, it must reach ready before the invoice can be released. nullable: true readOnly: true document_date: description: >- 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. format: date nullable: true type: string due_date: description: >- 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. format: date type: string dunning_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 has_document: description: >- Whether a usable invoice PDF is stored. A pending, rejected, or failed upload can have a document object while this flag is false. readOnly: true type: boolean id: description: Stable identifier of the invoice. format: uuid readOnly: true type: string invoice_number: description: >- 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. maxLength: 100 type: string overpaid: description: >- True when paid_amount exceeds amount. Over-payment is recorded, not refused; reconcile it in your own system. readOnly: true type: boolean paid_amount: description: >- Sum of all reported payments in the invoice currency. Payments beyond the invoice amount are accepted and counted here; balance never goes below zero. format: decimal pattern: ^-?\d{0,12}(?:\.\d{0,2})?$ readOnly: true type: string updated: description: Time at which the invoice was last updated. format: date-time readOnly: true type: string your_reference: description: >- 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. maxLength: 255 nullable: true type: string required: - access_mode - amount - archived - balance - created - debtor - document - due_date - dunning_state - has_document - id - invoice_number - overpaid - paid_amount - updated 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 AccessModeEnum: description: |- * `test` - Test * `production` - Production enum: - test - production type: string CurrencyEnum: description: |- * `EUR` - EUR * `USD` - USD * `GBP` - GBP * `CHF` - CHF enum: - EUR - USD - GBP - CHF type: string DocumentSummary: properties: download_url: description: >- Authenticated API URL for downloading the invoice PDF; null unless the document is ready. format: uri nullable: true readOnly: true type: string id: description: Stable identifier of the invoice document. format: uuid readOnly: true type: string status: allOf: - $ref: '#/components/schemas/CaseDocumentStatusEnum' description: >- Document ingestion state: pending while processing, ready after acceptance, rejected when content is rejected, or failed when ingestion/scanning cannot complete. Replace a rejected or failed document while the invoice is held to try again. readOnly: true required: - download_url - id - status type: object 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 CaseDocumentStatusEnum: description: |- * `pending` - pending * `ready` - ready * `rejected` - rejected * `failed` - failed enum: - pending - ready - rejected - failed type: string securitySchemes: tokenAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.