Skip to main content
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. 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: 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

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 for when an existing invoice or rental debt should instead be submitted as titled. 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. The Create claim schema 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.

​
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 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:
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.
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.

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