> ## 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.

# Claims

> Understand claim structures, amounts, evidence, and the metadata and events you can submit and read on claims and charges.

A **claim** is one monetary demand against a debtor. It records what is owed,
why it is owed, and the evidence and financial activity associated with that
amount.

Claims are first-class addressable resources, but a claim cannot exist without
a current order. Create a complete claim inline in `claims[]` when creating the
order, or stage one with `POST /v2/claims/` and the draft's `order_id`. An order
can contain several claims, and each claim keeps its own UUID and
`your_reference` even if paywise review moves it to another order.

Every claim read is complete: it includes `id`, current read-only `order_id`,
effective `status`, nullable `mandate_id`, `debtor_id`,
`additional_debtor_ids`, payments, all type-specific content, and timestamps.
Order responses embed the same complete projection in `claims[]`; they do not
define a different claim identity or a child-only URL.
Retired order-nested claim routes are unavailable: they return a hard JSON
`404` for every method, with no alias and no redirect. Use `/v2/claims/` and
its documented child routes with their trailing slashes.

## The two claim structures

The `Claim` response is a discriminated union on the required `type` property,
which mirrors `Order.type`. Send `type` on every claim create payload—inline
in `claims[]` or on `POST /v2/claims/`—or the request fails
with `400`. The claim `PATCH` never carries `type`: a claim's type is immutable.
Every claim response returns it.

| `type` | Structure | Use | Amount owner | Where it appears |
| - | - | - | - | - |
| `receivable` | `ReceivableClaim` | An invoice, contractual claim, rental month, related claim, or enforcement cost | `principal_amount` on the claim | Invoice and rental orders; enforcement costs in titled orders |
| `titled` | `TitledClaim` | An amount established by an enforceable title | `enforceable_title.amount` | Titled orders |

There is no `OrdinaryClaim` schema. Rental claims remain `ReceivableClaim`
resources and titled amounts use `TitledClaim`. On the write side,
`ClaimCreateRequest` is the matching `oneOf` of `ReceivableClaimCreateRequest`
and `TitledClaimCreateRequest`, discriminated on the same `type` value.

## Receivable claims

A `ReceivableClaim` (`type: "receivable"`) owns the business facts of the
demand directly:

| Field or child | What it represents |
| - | - |
| `principal_amount` | Original amount demanded before charges and payments |
| `subject_matter` | Plain-language reason for the demand |
| `document_reference` and `your_reference` | Your identifiers for matching the claim |
| `document_date`, `due_date`, and `delay_date` | When the demand arose, became due, and entered default |
| `legal_basis` | The underlying contract, transaction, or rental basis |
| `items` | Lines that make up the principal amount |
| `additional_charges` | Separate incidental amounts, such as eligible reminder fees |
| `reminders` | Payment reminders and their deadlines |
| `payments` | Money already received or reported against the claim |
| `documents` | Supporting claim evidence |
| `metadata`, `events` | Additional context supplied with the claim |

Not every field is required for every claim. Build the draft with the facts you
have, then use the finalization response to identify missing readiness data.
Invalid field combinations fail earlier with `400`; incomplete finalization
returns `422` with claim-scoped paths.

### Validation rules

| Field | Rule |
| - | - |
| `principal_amount.value` | At least `0.01`; a value that exceeds the representable total is `total_too_large`. |
| `items` | Up to 100 lines; `quantity` ≥ `0.001`. When present, the lines must sum to `principal_amount` within ±0.01 (`items_total_mismatch`). A line whose derived amount (`quantity` × `unit_price`) exceeds `99999999999999.99` is `400` on `items[i].amount` with code `total_too_large`. |
| `additional_charges` | Up to 50 entries; the resulting `total_amount` may never become negative (`negative_total`). |
| `reminders` | Up to 50 entries. |
| `subject_matter` | Up to 2000 characters, single line: control characters are rejected (`control_characters`). |
| `legal_basis.description` | Up to 2000 characters, multi-line. Required when the company has no configured default description. |
| `document_reference` | Unique within the order (`duplicate_document_reference`). |
| `is_disputed` | JSON boolean only; `"true"`, `1`, or `""` is `400` with code `invalid`. |
| Dates | Strict `YYYY-MM-DD` in ASCII digits, not before `1900-01-01`; any other spelling is `400` with code `invalid` and the message `Date has wrong format. Use YYYY-MM-DD.`. `document_date`, `contract_date`, and similar historical dates cannot lie in the future (`future`); `due_date`, `delay_date`, and reminder deadlines may. Rental claims require `due_date` ≥ `document_date`. `9999-12-30` is the latest accepted date: a rental `due_date` or a reminder `date`/`due_date` beyond it is `400` on that field with code `invalid` (`Date is too far in the future.`). |
| Single-line text | `subject_matter`, references, and other one-line fields reject control characters (`control_characters`). |
| Multi-line text | `items[].description`, `legal_basis.description`, and `dispute_reason` accept TAB, LF, and CR; `\r\n`, `\r`, U+2028, and U+2029 are stored as `\n`, the value is NFC-normalized, invisible format characters are stripped, and any other control character is `control_characters`. These three fields (like the withdraw `reason`) reject non-string values with `400` and code `invalid`, whereas `title`, `body`, `text`, `your_reference`, `street`, `issuing_authority`, and `file_number` coerce a JSON number to its string form. |

On reads, `claims[]` is ordered oldest-first (the order in which you created
the claims), and `Order.your_reference` is the `your_reference` of the oldest
claim.

## Titled claims

A `TitledClaim` (`type: "titled"`) represents a demand whose amount and legal
authority are established by an enforceable title. The embedded `enforceable_title` owns:

* the gross amount to enforce;
* title kind, issuing authority, and file number;
* issue, service, and legal-effect dates; and
* the primary enforceable-title document.

Do not also send `principal_amount`, claim dates, legal basis, items, charges,
reminders, or generic claim documents on that titled claim. Its response
uses `principal_amount: null`, while `total_amount` reflects
`enforceable_title.amount`. A `titled` claim stays `titled` for its lifetime:
after `DELETE …/enforceable-title/` it reads `enforceable_title: null` and
`total_amount: null` until `PUT` recreates the title (`201`).

Enforcement costs belong in separate `ReceivableClaim` entries within the same
titled order. See
[Orders](/api-docs/case-management-api/concepts/orders#titled-orders) for
when an existing invoice or rental debt should instead be submitted as titled.

## Legal basis codes

For a `ReceivableClaim`, `legal_basis.claim_type_code` identifies the actual
contract or transaction from which the claim arose. The table below contains
all 56 selectable codes and their German labels from the current OpenAPI
request schema. The codes are not a continuous numeric range; for example,
H47 is not a valid choice.

| Code | German label |
| - | - |
| `H01` | Anzeigen in Zeitungen u.a. |
| `H02` | Ärztliche oder zahnärztliche Leistung |
| `H03` | Bürgschaft |
| `H04` | Darlehensrückzahlung |
| `H05` | Dienstleistungsvertrag |
| `H06` | Frachtkosten |
| `H07` | Geschäftsbesorgung durch Selbständige |
| `H08` | Handwerkerleistung |
| `H09` | Heimunterbringung |
| `H10` | Hotelkosten |
| `H11` | Kaufvertrag |
| `H12` | Kontokorrentabrechnung |
| `H13` | Krankenhauskosten-Pflege/Behandlung |
| `H14` | Lagerkosten |
| `H15` | Leasing/Mietkauf |
| `H16` | Lehrgangs-/Unterrichtskosten |
| `H17` | Miete für Geschäftsraum einschl. Nebenkosten |
| `H18` | Miete für Kraftfahrzeug |
| `H19` | Miete für Wohnraum einschl. Nebenkosten |
| `H20` | Mietnebenkosten - auch Renovierungskosten- |
| `H21` | Miete |
| `H22` | Mitgliedsbeitrag |
| `H23` | Pacht |
| `H24` | Rechtsanwalts-/Rechtsbeistandshonorar |
| `H25` | Rentenrückstände |
| `H26` | Reparaturleistung |
| `H27` | Rückgriff aus Versicherungsvertrag wegen Unfall/Vorfall |
| `H28` | Schadenersatz aus Vertrag |
| `H29` | Schadenersatz aus Unfall/Vorfall |
| `H30` | Scheck/Wechsel |
| `H31` | Scheck-/Wechselprovision(1/3 %) |
| `H32` | Scheck-/Wechselunkosten - Spesen/Protest- |
| `H33` | Schuldanerkenntnis |
| `H34` | Speditionskosten |
| `H35` | Tilgungs-/Zinsraten |
| `H36` | Überziehung des Bankkontos |
| `H37` | Ungerechtfertigte Bereicherung |
| `H38` | Unterhaltsrückstände |
| `H39` | Vergleich, außergerichtlicher |
| `H40` | Vermittlungs-/Maklerprovision |
| `H41` | Versicherungsprämie/-beitrag |
| `H42` | Versorgungsleistung - Strom, Wasser, Gas, Wärme- |
| `H43` | Warenlieferung/-en |
| `H44` | Werkvertrag/Werklieferungsvertrag |
| `H45` | Zeitungs-/Zeitschriftenbezug |
| `H46` | Zinsrückstände/Verzugszinsen |
| `H61` | Wahlleistungen bei stationärer Behandlung |
| `H70` | Kindertagesstättenbeitrag |
| `H75` | Reisevertrag |
| `H76` | Telekommunikationsleistungen |
| `H77` | Krankentransportkosten |
| `H78` | Tierärztliche Leistung |
| `H79` | Verpflegungskosten |
| `H80` | Rückgriff aus Bürgschaft oder Garantie |
| `H90` | Wohngeld/Hausgeld für Wohnungseigentümergemeinschaft |
| `H95` | Beiträge zur privaten Pflegeversicherung |

The [Create claim schema](/api-docs/case-management-api/reference/claims/create-claim)
is the machine-readable authority for these values.

Only three codes need special order-level handling:

* H17 identifies commercial rent and is accepted only in a `rental` order.
* H19 identifies residential rent and is accepted only in a `rental` order.
* K014 identifies enforcement costs in a `titled` order. Omit the code there;
  paywise derives it.

One rental order cannot mix H17 and H19 claims. For all other receivable claims,
choose the code that describes the real underlying obligation and validate it
against the current
[Create claim schema](/api-docs/case-management-api/reference/claims/create-claim).

## Amounts, charges, and payments

Keep amount ownership unambiguous:

* `ReceivableClaim.principal_amount` is the original principal.
* `TitledClaim.enforceable_title.amount` is the gross titled amount.
* `additional_charges` are separate from the principal.
* `payments` record money received and remain separate entries.

For invoice and rental orders, `total_amount` is the current open value of the
claim and never drops below zero: a payment reported on a draft claim that
exceeds its open value is rejected with `400 overpayment`, and a `PATCH` that
would lower `principal_amount` or `additional_charges` below the payments
already recorded fails the same way. Titled order totals remain gross: title
amounts and eligible receivable claim amounts are reported separately from
payments. Do not calculate a second titled principal from compatibility fields.

See [Payments](/api-docs/case-management-api/concepts/payments) for the
draft-to-mandate reporting boundary.

## Metadata and events

Claims accept optional `metadata` and `events` arrays when created, both inline
in an order and through the top-level claim collection. This applies to
receivable and titled claims, including rental claims and enforcement costs.
Each `additional_charges[]` entry on a receivable claim can carry its own
metadata and events.

Metadata retains the v1 list of `{type, value}` objects. It is not a dictionary:
multiple entries with the same `type` are allowed and retained. The allowed
types depend on the resource. Claims and additional charges share the claim
metadata types; debtors and payments have their own enums in the reference.

Events describe facts you supply about the debt, such as a delivery. They are
separate from webhook events and paywise's published mandate history. Each
event uses `type`, `title`, and the historical spelling `occurence` for its
timestamp, plus optional nullable `your_reference`, `description`, and
`location`. Keep `occurence` exactly as written when porting v1 payloads.

For example, include this context in a claim creation payload:

```json theme={null}
{
  "metadata": [
    {"type": "comment", "value": "Goods received by the customer."},
    {"type": "transaction:reference", "value": "TX-2026-0042"},
    {"type": "comment", "value": "Delivery receipt attached separately."}
  ],
  "events": [{
    "type": "delivery",
    "title": "Goods delivered",
    "occurence": "2026-06-03T10:00:00Z",
    "your_reference": "DEL-0042",
    "description": null,
    "location": null
  }]
}
```

Use the resource's declared event types: for example, `delivery` on a claim,
`registration` on a debtor, or `invoice` and `transaction` on an additional
charge. A type allowed on one resource is not automatically allowed on another.

Reads return the stored context, including historical v1 values and duplicate
metadata types. No reimport is needed. Include the arrays when creating new
records; there are no dedicated metadata/event editing endpoints, and explicit
`metadata` or `events` on a debtor or claim `PATCH` is rejected. An unrelated
PATCH preserves the existing context.

<Warning>
  Replacing `additional_charges` on a draft claim still replaces the complete
  array. Include every charge you want to keep and its desired metadata/events
  in the replacement entries. Omitting `additional_charges` preserves its
  existing entries and context; sending `[]` removes the charges.
  Historical reads may contain types no longer accepted on new writes. Check
  the current input enums before replacing charges; do not blindly copy a read
  payload or discard unsupported historical context.
</Warning>

## Claim lifecycle

Create claims inline with the order or add them through `POST /v2/claims/`.
Only standalone creation accepts `order_id`; clients cannot PATCH it. While the
current order is `draft`, you can retrieve, patch, or delete the claim and
manage its title, documents, and payments through `/v2/claims/{claim_id}/...`.

Finalization is order-level and accepts an empty body or exactly `{}`. It
revalidates and submits every claim currently assigned to that order together.
Claim status follows the
effective order lifecycle through `draft`, `submitted`,
`awaiting_client_response`, `rejected`, or `withdrawn`, and ends at
`accepted`. Once accepted, the claim's `mandate_id` identifies the collection
case; mandate state owns all later processing.

Paywise review may merge or split orders and thereby change a claim's
`order_id`, but only among orders with identical frozen debtor UUID sets. The
client cannot move it. Its UUID, business data, payments, title, documents, and
child URLs stay unchanged. A concurrent draft command normally resolves the
new parent and retries; if movement prevents a stable lock after bounded
retries, `409 claim_moved_retry` tells you to retry the same logical command.
Any draft-only PATCH or DELETE after submission returns
`409 claim_not_editable`. `POST /v2/claims/` whose `order_id` names an order
that is no longer a draft answers the same code. For a finalized order the
`detail` reads
`The order is no longer a draft; claims can only be added to draft orders.`; a
merged order answers with `Order was merged into another order.` An expired
draft is different: every claim command on it — create, `PATCH`, `DELETE`,
and the claim's documents, payments, and enforceable title — answers
`409 order_expired`. Branch on the code, not on the `detail`.

Never create a replacement claim merely because its order has progressed or
moved. Store its UUID, read it directly with `GET /v2/claims/{id}/`, and use
the current `order_id` only as a relationship. Do not scan orders or follow
`merged_into` to locate it.

## Related reference

* [POST `/v2/claims/`](/api-docs/case-management-api/reference/claims/create-claim)
* [GET `/v2/claims/{id}/`](/api-docs/case-management-api/reference/claims/get-claim)
* [PATCH `/v2/claims/{id}/`](/api-docs/case-management-api/reference/claims/update-claim)
* [GET `/v2/claims/{claim_id}/enforceable-title/`](/api-docs/case-management-api/reference/claims/get-enforceable-title)
* [POST `/v2/claims/{claim_id}/payments/`](/api-docs/case-management-api/reference/claims/create-claim-payment)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.