> ## 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. # Mandates > Understand main mandates, subcases, shared claims and balances, case-specific states, published history, and reference numbers. A mandate is the read-only case created or extended when an order is accepted. It is not necessarily one-to-one with an order: multiple accepted orders can contribute claims to the same main mandate. ## Main cases and subcases A case consists of one **main mandate** and, where applicable, **subcases** for other liable persons or entities. Each mandate represents a debtor liable for the shared debt. Non-liable representatives do not receive subcases. The structure depends on the liable parties and their legal form: | Situation | Main case | Subcases | | - | - | - | | Joint debtors, such as joint tenants | One of the liable debtors | The other liable debtors | | GbR | The GbR | Its liable partners (*Gesellschafter*) | | OHG | The OHG | Its liable partners (*Gesellschafter*) | | Partnerschaftsgesellschaft (PartG) | The partnership | The partners liable for the particular claim | | KG | The KG | Its personally liable partners (*Komplementäre*) | | GmbH & Co. KG | The GmbH & Co. KG | Its personally liable partner, the Komplementär-GmbH | For private co-debtors, the choice of which debtor gets the main case is organisational. **Claims and the legal balance are shared.** Every subcase repeats the main case's claims and legal balance so it can be displayed independently. The balance is always identical across the main case and its subcases. These are views of the same debt: never add their balances together. The `legal_balance` object is published under the generated schema component `MandateLegalBalance`. The component name has no version label; its JSON shape and the amounts it represents are unchanged. **States can differ.** Although they usually align, read each mandate's own `state` for its legal stage, processing state, and payment state. Each dimension contains a stable machine `code`, translation-ready `label_key`, and current `label`. Published history entries explain events but do not replace these state fields. A main mandate has `main_case: null`; its `subcases` lists the related subcases. A subcase references its main mandate through `main_case` and has `subcases: []`. A case with only one debtor has `main_case: null` and `subcases: []`. **The structure can grow after acceptance.** paywise can identify additional liable parties and create subcases during processing. For example, a client may submit a GmbH & Co. KG, and paywise then identifies its Komplementär and creates the corresponding subcase. An initially empty `subcases` list can therefore change later; do not treat the case structure as fixed at acceptance. ### The debtor on a mandate Every mandate — main case and subcase, in the list and the detail, and in the `main_case` and `subcases` references — carries its debtor as a `MandateDebtor`: the identity, legal form, metadata, and events paywise accepted for that case, without an `id`. It is a snapshot of the case, not a debtor resource: `GET /v2/debtors/` does not list it and you cannot address or reference it. To reuse the party for a new order, send the reusable debtor's UUID, which the order carries as `debtor.id` and `additional_debtors[].id`. `GET /v2/mandates/{id}/history/` returns the statuses paywise published to the client. For a main mandate it combines the main track and all valid subcases; for a subcase it returns that subcase only. Every entry identifies its track in `source_mandate`, keeps all linked items in `related_resources`, and lists published files in `attachments`. One entry remains one published status even when it contains several links or files. `description` and `text` are plain text: HTML entities are decoded and paragraph boundaries become spaces. ## Reference numbers `reference_number` is the paywise case-file number (Aktenzeichen). In rare cases paywise re-keys a case; the current number then moves into `previous_reference_numbers`, a read-only list that is otherwise empty. Store the mandate `id` as your durable key. If you only hold a reference number, `GET /v2/mandates/?reference_number=…` matches the current number by substring and any previous number exactly, both case-insensitively. The `created_after` and `created_before` filters take a timezone-aware RFC 3339 timestamp only (for example `2026-09-01T00:00:00Z`); a date-only or naive value is `400` on `created_after` or `created_before` with code `invalid_parameter`. ## Find mandates `GET /v2/mandates/` returns main cases, newest first by default. `ordering` accepts `name` (the debtor's display name), `created`, `amount` (the main case's total), and `status` (the latest published status title). 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`. `q` follows the paywise portal search. It matches debtor names without regard to accents, your debtor reference, current and previous case reference numbers, and claim and document references by substring. From three characters it also matches the titles, texts, and event codes of published statuses. A UUID matches the case, one of its subcases (returning the main case), or one of its claims. A debtor UUID matches nothing because the mandate's debtor snapshot has no public `id`. Only the debtor-name and your-debtor-reference arms are limited to production-mode debtors; the case, claim, document, status, and UUID arms retain their stated scopes. `requests` filters by request-to-client state: `has_open_requests_to_client`, `has_answered_requests_to_client`, or `has_no_requests_to_client`. In every category only published requests count; an unpublished staff draft is invisible to the client. Archived cases are hidden unless you pass `archived`. With `updated_since` and no explicit `archived`, the list returns both archived and active cases so an incremental sync observes an archival change. `updated_since` also takes precedence over `ordering`: results use the synchronization order, `updated_at` and then `id`. Opening a case in the paywise portal does not move its `updated_at`. ## Closed mandates A mandate whose `state.processing.code` is `ended`, `canceled_by_client`, or `canceled_by_service_provider`, or whose `archived` flag is `true`, no longer accepts payment reports: `POST /v2/mandates/{id}/payments/` answers `409 conflict` with `Cannot report a payment on a closed mandate.` Reads, messages you are still allowed to send, and history stay available. See [Payments](/api-docs/case-management-api/concepts/payments#overpayment-and-duplicates). ## Related reference * [GET `/v2/mandates/{id}/`](/api-docs/case-management-api/reference/mandates/get-mandate) * [GET `/v2/mandates/{id}/history/`](/api-docs/case-management-api/reference/mandates/get-mandate-history) * [GET `/v2/mandates/{id}/history/{entry_id}/attachments/{file_id}/download/`](/api-docs/case-management-api/reference/mandates/download-mandate-history-attachment) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.