> ## 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. # List invoices > 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. **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](/api-docs/mahnservice-api/introduction). ## OpenAPI ````yaml api-docs/mahnservice-api/openapi.json GET /mahnservice/v1/invoices/ openapi: 3.0.3 info: title: paywise Mahnservice API version: v1 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 per-operation windows of 600 reads or 120 writes per minute; a `429` carries `Retry-After`. servers: - url: https://api.paywise.de description: Production environment security: [] tags: - name: Info description: The authenticated credential and its context. - name: Debtors description: Debtors invoices are addressed to. - name: Invoices description: Held invoices, their release, payments and documents. - name: Dunning flows description: Dunning flow configurations referenced by invoices. externalDocs: url: https://docs.paywise.de/api-docs/mahnservice-api/introduction paths: /mahnservice/v1/invoices/: get: tags: - Invoices summary: List invoices 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: list-invoices parameters: - name: limit required: false in: query description: Number of results to return per page; defaults to 10. schema: type: integer default: 10 maximum: 100 minimum: 1 - name: offset required: false in: query description: Zero-based index of the first result; defaults to 0. schema: type: integer default: 0 minimum: 0 responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedInvoiceList' description: '' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '400': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '401': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '403': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string '429': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string 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: type: integer minimum: 1 '500': description: Standard error response. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Paywise-Request-Id: description: >- Fresh server-assigned correlation id for this response. Caller-provided request ids are ignored. schema: type: string format: uuid X-Paywise-Environment: description: Environment that produced the response. schema: enum: - production - sandbox type: string Cache-Control: description: >- Cacheability directive. Authenticated responses use `private, no-store`; the legal-form catalog may use `private, max-age=86400`. schema: type: string security: - tokenAuth: [] components: schemas: PaginatedInvoiceList: type: object required: - count - results properties: count: type: integer example: 123 description: Total number of matching resources. next: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=400&limit=100 description: URL for the next page, or null on the last page. previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?offset=200&limit=100 description: URL for the previous page, or null on the first page. results: type: array items: $ref: '#/components/schemas/Invoice' description: Resources returned for the requested page. Error: type: object properties: detail: type: string description: Short human-readable summary of the error. code: type: string description: Machine-readable error category. errors: type: array items: $ref: '#/components/schemas/ErrorItem' description: Field-level validation errors, when applicable. required: - detail - code additionalProperties: false Invoice: type: object 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: id: type: string format: uuid readOnly: true invoice_number: type: string maxLength: 100 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. amount: type: string format: decimal pattern: ^[0-9]{1,10}(?:\.[0-9]{1,2})?$ 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. 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. due_date: type: string format: 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. document_date: type: string format: date nullable: true 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. your_reference: type: string nullable: true maxLength: 255 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. debtor: type: string format: uuid 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. access_mode: allOf: - $ref: '#/components/schemas/AccessModeEnum' readOnly: true description: >- Legacy data-isolation mode inherited from the token, not the API host environment. Modern sandbox and production credentials both use production. dunning_state: allOf: - $ref: '#/components/schemas/MahnserviceDunningStateEnum' readOnly: true nullable: true 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. archived: type: boolean readOnly: true 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. has_document: type: boolean readOnly: true description: >- Whether a usable invoice PDF is stored. A pending, rejected, or failed upload can have a document object while this flag is false. document: allOf: - $ref: '#/components/schemas/DocumentSummary' readOnly: true nullable: true 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. balance: type: string format: decimal pattern: ^-?\d{0,12}(?:\.\d{0,2})?$ readOnly: true 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. paid_amount: type: string format: decimal pattern: ^-?\d{0,12}(?:\.\d{0,2})?$ readOnly: true 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. overpaid: type: boolean readOnly: true description: >- True when paid_amount exceeds amount. Over-payment is recorded, not refused; reconcile it in your own system. created: type: string format: date-time readOnly: true updated: type: string format: date-time readOnly: true required: - access_mode - amount - archived - balance - created - debtor - document - due_date - dunning_state - has_document - id - invoice_number - overpaid - paid_amount - updated ErrorItem: type: object properties: field: type: string nullable: true 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. code: type: string description: Machine-readable field error code. message: type: string description: Human-readable explanation of the field error. required: - field - code - message additionalProperties: false CurrencyEnum: enum: - EUR - USD - GBP - CHF type: string description: |- * `EUR` - EUR * `USD` - USD * `GBP` - GBP * `CHF` - CHF AccessModeEnum: enum: - test - production type: string description: |- * `test` - Test * `production` - Production MahnserviceDunningStateEnum: enum: - held - pending - active - paused - completed - paid - cancelled - written_off - inkasso type: string description: |- * `held` - Held * `pending` - Pending * `active` - Aktiv * `paused` - Pausiert * `completed` - Abgeschlossen * `paid` - Paid * `cancelled` - Storniert * `written_off` - Ausgebucht * `inkasso` - An Inkasso übergeben DocumentSummary: type: object properties: id: type: string format: uuid readOnly: true status: allOf: - $ref: '#/components/schemas/CaseDocumentStatusEnum' readOnly: true 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. download_url: type: string format: uri readOnly: true nullable: true description: >- Authenticated API URL for downloading the invoice PDF; null unless the document is ready. required: - download_url - id - status CaseDocumentStatusEnum: enum: - pending - ready - rejected - failed type: string description: |- * `pending` - pending * `ready` - ready * `rejected` - rejected * `failed` - failed securitySchemes: tokenAuth: type: http scheme: bearer ````