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:
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 themain_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 whosestate.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.