> ## 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 a dunning flow

> Read-only dunning-flow (Mahnlauf) configuration. Flows are company
config with no test/production split, so both token modes read the same
flows; configuration itself stays in the paywise portal (design D-portal:
the public API keeps flows read-only).

<Warning>
  **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).
</Warning>


## OpenAPI

````yaml api-docs/mahnservice-api/openapi.json GET /mahnservice/v1/dunning-flows/{uuid}/
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/dunning-flows/{uuid}/:
    get:
      tags:
        - Dunning flows
      summary: Get a dunning flow
      description: >-
        Read-only dunning-flow (Mahnlauf) configuration. Flows are company

        config with no test/production split, so both token modes read the same

        flows; configuration itself stays in the paywise portal (design
        D-portal:

        the public API keeps flows read-only).
      operationId: get-dunning-flow
      parameters:
        - in: path
          name: uuid
          schema:
            type: string
            format: uuid
          required: true
          description: UUID of the dunning flow in this request.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DunningFlow'
          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
        '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
        '404':
          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:
    DunningFlow:
      type: object
      description: |-
        A configured dunning flow (Mahnlauf). `levels` is the ordered level
        configuration; `level_count` matches the summary shape embedded in
        `GET /invoices/{uuid}/dunning/`.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          readOnly: true
        is_default:
          type: boolean
          readOnly: true
          description: >-
            Current enrollment configuration. Non-default rows include
            historical versions still referenced by existing invoices; is_active
            does not identify the latest version.
        is_activated:
          type: boolean
          readOnly: true
          description: >-
            Whether sending has been activated for this flow in the paywise
            portal. Released invoices remain pending until activation, unless
            another hold applies.
        is_active:
          type: boolean
          readOnly: true
          description: >-
            False = the flow was deactivated by paywise (no new enrollments;
            invoices already running on it continue). Not a deletion.
        fees_enabled:
          type: boolean
          readOnly: true
          description: >-
            Master switch for dunning fees. A level's fee is charged only when
            this and the level's fee_enabled are true.
        level_count:
          type: integer
          readOnly: true
        levels:
          type: array
          items:
            $ref: '#/components/schemas/DunningFlowLevel'
          readOnly: true
          description: >-
            Dunning-level configurations in level order. Flow configuration is
            read-only through this API.
      required:
        - fees_enabled
        - id
        - is_activated
        - is_active
        - is_default
        - level_count
        - levels
        - name
    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
    DunningFlowLevel:
      type: object
      description: One escalation level of a dunning flow.
      properties:
        level:
          type: integer
          readOnly: true
          description: One-based position of this level in the dunning flow.
        days_after_previous:
          type: integer
          readOnly: true
          description: >-
            Delay in days after the previous level; for level 1, measured from
            the invoice due date.
        channel:
          allOf:
            - $ref: '#/components/schemas/ChannelEnum'
          readOnly: true
          description: >-
            Configured delivery channel for this level: email, postal letter, or
            both.
        fee_enabled:
          type: boolean
          readOnly: true
          description: >-
            Whether this level charges a dunning fee; effective only when the
            flow's fees_enabled is also true.
        fee_amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,2})?$
          readOnly: true
          description: >-
            Configured dunning fee for this level in EUR. Charged only when both
            the flow and this level enable fees.
      required:
        - channel
        - days_after_previous
        - fee_amount
        - fee_enabled
        - level
    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
    ChannelEnum:
      enum:
        - email
        - letter
        - both
      type: string
      description: |-
        * `email` - E-Mail
        * `letter` - Brief
        * `both` - E-Mail & Brief
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer

````