Skip to main content
An order is the submission you assemble for paywise: it selects a debtor, groups one or more claims, and owns their supporting data. Edit it while it is a draft, then finalize it for review. After acceptance, the order remains the submission record and the mandate becomes the collection case you follow. Every collection order uses the same draft-to-mandate lifecycle. The type describes what the debt is based on and therefore which data and evidence the order needs. It does not describe how urgent, difficult, or advanced the case is.

​
Choose by what supports the debt

​
Invoice orders

Choose an invoice order when the claim is still based on the original transaction or obligation. Typical examples are an unpaid invoice for goods or services, a contractual fee, or another untitled claim that paywise should collect from its underlying legal basis. Despite the name, the variant is not limited to claims represented by a formal invoice. It is the standard choice whenever neither rental-specific rules nor an enforceable title define the case. Its claims use ReceivableClaim, and each claim carries its own amount, dates, legal basis, charges, payments, reminders, and supporting documents. Example: A consulting company wants to collect an overdue €1,250 invoice for services it delivered. No rental agreement or enforceable title is involved, so it creates an invoice order with one ReceivableClaim. Do not choose invoice for an unpaid monthly rent claim that needs H17/H19 handling, or when collection is based on an enforceable title rather than the original obligation. Submit an invoice order →

​
Rental orders

Choose a rental order when the order centers on unpaid rent owed under one rental agreement. Use H17 for commercial rent or H19 for residential rent. The agreement supplies shared context such as the property, monthly Warmmiete, contract conclusion date, and the rule used to derive rent due dates. A rental order is useful when several unpaid rental months belong to the same agreement: each month remains an individual ReceivableClaim, while the shared agreement and server-side date rules keep the claims consistent. One order can contain either H17 or H19 rental claims, never both. Other receivable claims may coexist, but at least one H17/H19 claim is required before finalization. Example: A residential tenant owes rent for February and March under the same lease. Create one rental order with two H19 claims—one for each rental month—and one shared rental agreement. Do not choose rental merely because the debtor happens to be a tenant. Use it when unpaid rent itself is part of the order and the rental agreement is the relevant shared context. Submit a rental order →

​
Titled orders

Choose a titled order when a court judgment or order, an enforceable court settlement, or an enforceable notarial deed has already established the amount to enforce. In this variant, paywise proceeds from the enforceable title rather than reconstructing the claim from the original invoice, contract, or rent obligation. Each titled amount is represented by a TitledClaim. Its enforceable_title owns the amount, title kind, issuing authority, file number, dates, and primary title document. Enforcement costs can be added as separate ReceivableClaim entries; paywise derives their K014 claim code. Example: An unpaid invoice has already resulted in a Vollstreckungsbescheid. Create a titled order whose TitledClaim carries the amount and court document from that title; do not submit the old invoice amount again as a separate principal claim. Choose titled even when the debt originally began as an invoice or rental claim if the enforceable title is now the legal basis for collection. Do not duplicate the underlying pre-title claim as another principal amount. Submit a titled order →

​
Compare the API shape

The type field selects the data that belongs to the order: type is always returned, defaults to invoice when omitted from create, and cannot change after creation. A type-changing PATCH returns 409. Filter the unified order list exactly with GET /v2/orders/?type=invoice, rental, or titled.

​
Starting approach and enforcement

For invoice and rental orders, starting_approach selects extrajudicial or judicial. It may be null while the draft is incomplete. For titled orders, enforcement is implicit in the order type. Omit starting_approach and creditor_obligation_fulfilled on both create and update: supplying either field, including null, returns 400. "enforcement" is not a public starting_approach value. The titled-order response omits both fields, and paywise routes the accepted case into enforcement automatically. Instead, confirm success_fee_confirmed: true before finalization.

​
Construct inline or in stages

All three variants support atomic inline claim creation. First create or reuse each debtor through /v2/debtors/. One POST /v2/orders/ then references the primary debtor as debtor_id, references other liable parties as additional_debtor_ids, and may include complete claims with their payments and documents. If any value is invalid, none of the order aggregate is created. Reuse the same Idempotency-Key and identical body after an ambiguous outcome. You can instead create an incomplete draft and stage complete claims with POST /v2/claims/, supplying the draft’s UUID as request-only order_id. Claim, title, payment, and document commands use the stable claim UUID. This is useful when a contract, title, or supporting file arrives in a later step. Finalization validates and submits every claim currently assigned to the order; it does not make earlier commands atomic with one another.

​
Claims in each variant

Invoice and rental orders use ReceivableClaim. Titled orders use TitledClaim for titled amounts and may add ReceivableClaim entries for enforcement costs. Every claim carries its own required discriminator type (receivable or titled): send it on create, and read it back on every claim response. Like the order type, it cannot change after creation. See Claims for amount ownership, claim fields, charges, payments, and the H17, H19, and K014 rules.

​
Variant-owned singleton resources

A rental order always owns one rental agreement, even if the initial draft omits its data. Read or update it through GET /v2/orders/{order_id}/rental-agreement/ and PATCH /v2/orders/{order_id}/rental-agreement/. It cannot be deleted separately from its draft order. Each titled claim owns one enforceable title. It can be created inline with the claim or managed through its dedicated GET, PUT, PATCH, and DELETE route. PUT creates the title (201) or completely replaces writable title metadata (200) while leaving documents untouched; an empty body is 400. PATCH changes supplied fields. DELETE removes the title metadata only: it answers 409 with the offending document_ids[] while title documents still exist, so delete those first. The claim keeps type: titled with enforceable_title: null and total_amount: null; it must receive a new title through PUT or be deleted before finalization (readiness reports claims.{claim_id}.enforceable_title / required). Subtype routes return 404 when the parent has the wrong type or does not belong to the selected company. Supplying subtype data on the wrong order or claim command returns 400.

​
Shared lifecycle and limits

Every type supports draft correction, finalization, read/verification, eligible withdrawal, and draft-order deletion. The same limits also apply: 50 claims per order, 20 inline documents per command across all included parents, and 10 MiB per document. The error split stays stable: 400 for invalid command data, 409 for immutable fields or resource/lifecycle conflicts, and 422 only when an incomplete draft cannot be finalized. Webhook events remain reference-only; fetch order_url to receive the current discriminated order representation.

​
Lifecycle

An order begins as a mutable draft. Finalization validates the complete aggregate and moves it to submitted. The brief internal review transition is also exposed as submitted; there is no separate public “in review” state.

​
Draft and finalization

Draft mutations refresh the rolling 90-day inactivity deadline, which the order exposes as expires_at (updated_at plus 90 days; null once finalized and for portal-created orders). A PATCH whose values equal the stored ones (including {}) is not a mutation: it leaves updated_at, the ETag, and expires_at untouched. The same holds for a no-op PATCH on a claim, message, or debtor and a no-op PUT/PATCH on the enforceable title: the response is 200 and updated_at, the ETag, and expires_at do not move. A debtor frozen by an order under review answers 409 even to PATCH {}. Expiry applies only to unfinished API-created orders. Once the deadline has passed the order reads status: "expired" and matches GET /v2/orders/?status=expired. expired is terminal: every write on the order — PATCH and DELETE, finalize, withdraw, POST /v2/claims/ naming it, and the claim, document, payment, enforceable-title, rental-agreement, and message commands below it — answers 409 order_expired (The draft order has expired and can no longer be changed.), and nothing refreshes or revives the deadline. The daily sweep later hard-deletes the owned draft aggregate, preserves reusable debtor records, and emits the separate order.expired webhook event, after which the order answers 404. Finalization accepts an empty body or exactly {}; any member is 400 validation_error with unknown_field. It validates company readiness, credential terms and Partner access, debtor notification coverage and address, variant-specific order decisions, claims, documents, and EUR amounts. Each ReceivableClaim needs a non-empty subject_matter or at least one document. A validation failure leaves the draft editable. The API terms are checked at finalization, not at draft creation: a credential whose current terms have not been accepted answers 403 terms_acceptance_required and the draft stays editable. Command data is validated before the lifecycle is consulted:
  • debtor_id must be a canonical UUID. A non-string, malformed, or empty reference is 400 on debtor_id with code invalid; an invalid element of additional_debtor_ids is reported at additional_debtor_ids[i]. An unknown or other-company UUID is a neutral 404.
  • creditor_obligation_fulfilled is a JSON boolean only; "true", 1, or "" is 400 with code invalid.
  • success_fee_confirmed is a JSON boolean only; "true", "yes", 1, or 0 is 400 on success_fee_confirmed with code invalid (Must be a JSON boolean (true or false).).
  • additional_debtor_ids may not repeat a person or organization already part of the order: 400 on additional_debtor_ids with code duplicate and the message This person is already part of the order.
Rental finalization additionally requires a complete property address, positive monthly rent, contract conclusion date, and at least one consistent H17 or H19 claim. Titled finalization requires success_fee_confirmed: true and at least one complete TitledClaim with a positive amount, title metadata, and primary title document. Missing draft readiness returns 422 for every order type — invoice, rental, and titled — with public resource paths in errors[]; invalid command data returns 400, while immutable-field and lifecycle conflicts return 409. Readiness issues are keyed by resource path and carry an actionable English message; each public field is reported once: Before finalization you may delete the whole draft with DELETE /v2/orders/{id}/. This removes every owned subtype resource, claim, payment, and document while preserving the referenced reusable debtor records.

​
Submitted, awaiting response, and withdrawal

After a successful finalize, the order is immutable and submitted. It may temporarily become awaiting_client_response, then return to submitted after the client responds. Internal staff review remains publicly submitted. Use List order requests to client to find the published questions, then Answer order request to client to submit each answer. These routes use the order UUID and work before a mandate exists. All published questions must be answered before the order resumes. Attachments process asynchronously and become downloadable when ready. Withdrawal is allowed only after submission and before acceptance while the order is queued or awaiting a client response. It returns 409 if staff review has started or the order is draft, accepted, rejected, expired, or already withdrawn; on a draft the detail reads The order has not been finalized; delete the draft instead of withdrawing it. The optional reason is multi-line text: TAB, LF, and CR are accepted (line endings are stored as \n), any other control character is 400 with code control_characters, and a non-string value is 400 with code invalid. A client can also cancel a submitted order in the paywise portal. That is the same transition: the order reads withdrawn, and order.withdrawn fires once, whichever channel withdrew the order. If you ask paywise support to resume a withdrawn order, staff can return it to review: it reads submitted again and its updated_at advances, so the next updated_since scan returns it. No webhook event announces the resumption. Finalize is not repeatable. A second finalize on a submitted order answers 409 conflict with Order is already finalized.; on a withdrawn or decided order — including a finalize that races a concurrent withdrawal — the detail is Order is already finalized or withdrawn. An API withdrawal sends no e-mail to your company unless the order carries a confirmation_email. A rejected order cannot be deleted and rejection alone does not make its invoice number reusable. Resubmission is allowed only when every prior company match was withdrawn by the client.

​
Rejection

During review paywise may decline the order. It then reads status: "rejected" and carries a read-only rejection object, which is null in every other status:
  • reason is the plain-text wording of the rejection notice, formatting removed.
  • notified_to lists the status-update recipients configured for your company that the notice was delivered to. It never contains a debtor address and is empty when no notice was sent.
  • code identifies a standard rejection reason so you can branch on it without parsing reason. It is null when paywise staff wrote an individual reason; reason is then the only guidance.
The order.rejected webhook carries the order and company UUIDs plus the exact claim_ids snapshot captured at rejection; fetch the order to read the reason. A rejected order is final for your writes: it can be neither deleted nor withdrawn, and rejection alone does not make its invoice number reusable. paywise staff can still re-review it; it then reads submitted again, without a webhook event, and updated_since returns it.

​
Acceptance

accepted means paywise created or extended the legal mandate. The order stays as the immutable submission record; the mandate becomes the read model for case state and history. Acceptance also fixes the debtor snapshot used for the legal case, even though the reusable debtor record can still change. Acceptance associates each accepted claim with a mandate. The order reports that mandate’s UUID in its read-only mandate field, and the order.accepted webhook payload carries the same UUID as mandate_id next to mandate_url and the exact accepted claim_ids snapshot. The claim read also exposes mandate_id. Claim lifecycle status ends at accepted; the mandate owns all post-acceptance processing state and history.

​
Review can rearrange orders: merge and split

During review, paywise staff may consolidate submitted orders or move claims into a separate order. Merge, split, and unmerge are allowed only when the orders have identical frozen debtor UUID sets: the same primary debtor_id and the same unordered additional_debtor_ids. Claims keep their id, content, children, and your_reference, so the claim is the stable correlation unit; the set of orders holding your claims is not. Merge. An order whose claims were merged into another order reports status merged and names the surviving order in its read-only merged_into field. It will never become accepted itself. Do not use that pointer to locate a claim: continue reading each stored claim UUID, whose order_id reflects its current parent. If staff reverse the merge, the order returns to submitted and merged_into becomes null again. Orders merged before this field existed report draft with merged_into: null. A merged order is terminal for every write: PATCH, claim, rental-agreement, enforceable-title, document, and payment commands, finalize, withdraw, and DELETE all answer 409 conflict with Order was merged into another order. Reads stay 200 for audit history. Split. Claims moved out of an order appear in a new order under your company. The client cannot assign or patch order_id; only paywise review can move a claim. GET /v2/claims/{id}/ keeps working and returns the new order_id. The new order shows up in GET /v2/orders/ and fires its own order.accepted webhook when accepted. The source order keeps its remaining claims and proceeds normally.

​
List and sort orders

GET /v2/orders/ is newest first by default. ordering accepts name (the primary debtor’s display name, case-insensitive), created, amount (the sum of the order’s claim totals), and status (the public order status). Separate multiple terms with commas and prefix a term with - for descending order; ties are broken by id in the direction of the last term. An empty ordering parameter keeps the default. An unknown field or an empty comma-separated term is 400 on ordering with code invalid_parameter; the retired sort, direction, and search parameters are 400 unknown_parameter. When migrating an older list integration, sort=date&direction=asc becomes ordering=created, and sort=name becomes ordering=-name. With updated_since, the list keeps its synchronization order, updated_at and then id, even when ordering is also present. An order rejected, withdrawn, or finalized after your cursor therefore appears in the next scan.