> ## 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. # Orders > Choose invoice, rental, or titled orders and follow their lifecycle from draft through submission, review, and acceptance. An **order** is the submission you assemble for paywise: it selects a [debtor](/api-docs/case-management-api/concepts/debtors), groups one or more [claims](/api-docs/case-management-api/concepts/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](/api-docs/case-management-api/concepts/mandates) 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 | You want paywise to collect… | Choose | | - | - | | An unpaid claim based directly on an invoice, contract, delivery, service, or another underlying obligation | `invoice` | | Unpaid residential or commercial rent under a rental agreement | `rental` | | An amount that has already been established in an enforceable title | `titled` | ### 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 →](/api-docs/case-management-api/workflows/submit-an-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 →](/api-docs/case-management-api/workflows/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 →](/api-docs/case-management-api/workflows/submit-a-titled-order) ## Compare the API shape The `type` field selects the data that belongs to the order: | `type` | Order-specific data | Claim use | | - | - | - | | `invoice` | `starting_approach`, `creditor_obligation_fulfilled` | `ReceivableClaim` (claim `type: "receivable"`) | | `rental` | The same decisions plus one `rental_agreement` | H17/H19 rental claims and other `ReceivableClaim` entries (claim `type: "receivable"`) | | `titled` | `success_fee_confirmed` and no starting-approach decisions | `TitledClaim` (claim `type: "titled"`) plus K014 enforcement-cost `ReceivableClaim` entries (claim `type: "receivable"`) | `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/`](/api-docs/case-management-api/reference/orders/create-order) 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](/api-docs/case-management-api/concepts/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/`](/api-docs/case-management-api/reference/orders/get-rental-agreement) and [PATCH `/v2/orders/{order_id}/rental-agreement/`](/api-docs/case-management-api/reference/orders/update-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. ```mermaid theme={null} stateDiagram-v2 [*] --> draft draft --> submitted: finalize submitted --> awaiting_client_response awaiting_client_response --> submitted submitted --> accepted submitted --> rejected submitted --> withdrawn submitted --> merged: staff merges orders merged --> submitted: staff unmerges awaiting_client_response --> withdrawn withdrawn --> submitted: staff resumes on request rejected --> submitted: staff re-reviews draft --> expired: 90 days inactive ``` ### 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: | `field` | `code` | Meaning | | - | - | - | | `company.` | `required`, `invalid`, `country_mismatch`, … | Company master data that the company's administrator must complete in the paywise app (or the Partner via `PATCH /partner/v2/companies/{id}/`). | | `debtor_id.`, `additional_debtor_ids.{debtor_uuid}.` | `required`, `invalid` | Missing notification coverage, address, or identity data on a referenced debtor's stored record. | | `debtor_id.person.birth_date` | `minor_debtor` | A sole proprietor under 18 cannot be pursued. | | `additional_debtor_ids` | `legal_guardian_required` | The primary debtor is a minor consumer; reference an adult co-debtor. | | `claims.{claim_id}.` | `required`, `invalid_or_missing` | Missing claim data, such as `delay_date` on a consumer claim or `legal_basis.description` when the company has no default. | | `claims.{claim_id}.enforceable_title` | `required` | A titled claim without a title. | | `claims.{claim_id}.total_amount`, `totals.order_value` | `negative_total` | Charges and payments leave a non-positive amount. | Before finalization you may delete the whole draft with [DELETE `/v2/orders/{id}/`](/api-docs/case-management-api/reference/orders/delete-draft-order). 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](/api-docs/case-management-api/reference/orders/list-order-requests-to-client) to find the published questions, then [Answer order request to client](/api-docs/case-management-api/reference/orders/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: ```json theme={null} "rejection": { "reason": "Unfortunately we cannot accept this order: our request for the missing contract documents remained unanswered. Please submit the order again together with the documents.", "rejected_at": "2026-07-20T09:30:00Z", "notified_to": ["billing@example.test"], "code": "REJECTION_UNANSWERED_RTC" } ``` * `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. ## Related workflows * [Submit an invoice order](/api-docs/case-management-api/workflows/submit-an-order) * [Submit a rental order](/api-docs/case-management-api/workflows/submit-a-rental-order) * [Submit a titled order](/api-docs/case-management-api/workflows/submit-a-titled-order) ## Related reference * [POST `/v2/orders/`](/api-docs/case-management-api/reference/orders/create-order) * [POST `/v2/orders/{id}/finalize/`](/api-docs/case-management-api/reference/orders/finalize-order) * [POST `/v2/orders/{id}/withdraw/`](/api-docs/case-management-api/reference/orders/withdraw-order) * [DELETE `/v2/orders/{id}/`](/api-docs/case-management-api/reference/orders/delete-draft-order) * [GET `/v2/orders/{id}/`](/api-docs/case-management-api/reference/orders/get-order) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.