Royalty Statements v4
A royalty statement is the account a business partner's royalties are booked onto, and the document that is rendered from it. It carries the bookings as line items, the aggregated figures as a summary, the rendered files, the correspondence they were mailed with, and the invoice texts printed onto the document.
Internally a statement is an account of type provision, the sibling of an
order, which is why the two share every sub-resource but the summary and the
group identifiers.
Two things are worth knowing before reading further.
The statement is identified by a UUID on every version. It already was on v3 — unlike the rest of the API, where v3 identifies by legacy integer and v4 by UUID. Its sub-resources did not follow: line items, files, correspondence and recipients are addressed by an integer id on v4 as well; only texts take a UUID.
Money is not uniform. Line items and the summary use the v4
monetary value object,
{"value": 20.00, "currency": "EUR"}, with the value in major units. The
statement's own total block does not: it still carries the v3 layout, a flat
value in munits plus a sibling <field>_currency. See total on the
Royalty Statement schema below.
Finalizing fixes the statement. While it is open the sums are estimates
and everything is writable. Setting invoiced: true writes the sums and
assigns the invoice number, after which line items and texts refuse writes
with 403 Permission denied, so the rendered document and the data behind it
cannot diverge.
Endpoints
GET /resource/v4/royalty_statements
Retrieve a list of royalty statements
Description
Returns the realm's royalty statements, paginated. See Resource Queries for the filter and pagination syntax.
Only accounts of type provision are listed, for performance reasons. An
inter_realm statement is reachable by id but does not appear here.
Input parameters
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
auto |
boolean | No | Whether the statement came from the automatic royalty run. Equality only. | |
business_partner_id |
integer | No | Statements of one business partner. This filter takes the partner's **legacy integer id**, on v4 as well — a UUID is read as 0 and matches nothing. The `_legacy_id` on a business partner reference is the value to pass. | |
invoiced |
boolean | No | `true` returns finalized statements, `false` open ones. Equality only. | |
page |
integer | No | Page number, starting at 1. | |
page_size |
integer | No | Entries per page. Statements default to 25, sub-resources to 100. `display` is accepted as a legacy alias. | |
q |
string | No | Full-text search over the statement's searchable text. An `a |
|
sort |
string | No | Sort field. Statements sort by `id` or `invoice_date`, both of which order by the account id; prefix with `-` for descending. | |
statement_run_id |
string | No | Statements of one statement run. Statement run ids are strings and are the same on every version. |
Responses
Refer to the common response description: royalty_statement_list.
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
POST /resource/v4/royalty_statements
Create a royalty statement
Description
Creates an open statement for the realm, dated today, and applies the
fields sent with it. business_partner is what makes the statement
useful; everything else can follow in a PUT.
The statement is created as a credit note with ungrouped invoice positions.
Request body
{
"name": "Tantiemen 2025/Q2",
"business_partner": {
"_id": "12838cc6-e617-11ee-a221-00505699575c"
},
"invoice_date": "2025-07-01"
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One royalty statement — the account a business partner's royalties are booked\nonto, and the document that is rendered from it.\n\nInternally a royalty statement is an account of type `provision` (or\n`inter_realm`), which is why it shares its sub-resources with orders: line\nitems, files, correspondence and [invoice texts](/v4/account_texts/) all look\nthe same on both parents.\n\nA statement is **open** until it is finalized, and finalizing is what fixes\nthe numbers: `invoice_number` is assigned, the sums are written, and the\nsub-resources stop accepting writes. See `invoiced`.\n",
"properties": {
"_id": {
"type": "string",
"description": "UUID of the statement. This is the identifier on **both** v3 and v4 — the\nroyalty statement resource already addressed by UUID before v4 — so it is\nthe one v4 object whose `_id` did not change with the version.\n",
"example": "9c1e6d45-dafd-4698-b68f-a7cf5495ee23"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"description": "URLs of the statement and of each of its sub-resources.",
"properties": {
"self": {
"type": "string"
},
"line_items": {
"type": "string"
},
"summary": {
"type": "string"
},
"group_identifiers": {
"type": "string"
},
"files": {
"type": "string"
},
"correspondence": {
"type": "string"
},
"texts": {
"type": "string"
}
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"name": {
"type": "string",
"description": "Human-readable name of the statement, shown in listings and on the\nrendered document.\n",
"example": "Tantiemen 2025/Q2"
},
"period": {
"type": "string",
"description": "Technical description of the settlement period, as the statement run wrote\nit. Free text, empty when the statement was created by hand.\n",
"example": "2025/Q2"
},
"invoice_date": {
"type": "string",
"description": "Invoice date in YYYY-MM-DD format.",
"nullable": true,
"example": "2025-07-01"
},
"invoice_number": {
"type": "integer",
"description": "Invoice number, assigned when the statement is finalized. Null while the\nstatement is still open; read-only.\n",
"nullable": true,
"example": 918273
},
"invoiced": {
"type": "boolean",
"description": "Whether the statement has been finalized. Setting it to `true` in a `PUT`\n**finalizes the statement**: the sums are written and the invoice number is\nassigned. It cannot be set back to `false` — reopening is rejected with\n`400 Bad Request` (`account::cannot_reopen_account`) and is done through\nthe reopen RPC instead.\n\nOnce it is `true`, writes to the statement's line items and texts are\nrefused with `403 Permission denied`, so the rendered document and the data\nit was rendered from cannot diverge.\n"
},
"invoice_positions_grouped": {
"type": "boolean",
"description": "Whether line items are grouped by their reference on the rendered document\n(`false` prints every line item on its own).\n"
},
"auto": {
"type": "boolean",
"description": "Whether the statement was produced by the automatic royalty run rather than\ncreated by hand. Read-only.\n"
},
"cleared": {
"type": "boolean",
"description": "Whether the payout has been settled. Read-only."
},
"total": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement's sums.\n\n**This block is the one place in v4 that still carries the v3 money\nlayout**: a flat value in *munits* (1/100 of the currency unit) plus a\nsibling `<field>_currency`, rather than the\n[monetary value](/structured-fields/#monetary-value) object used everywhere else in\nv4 — including this resource's own line items and summary. It is built\nwithout going through the version-aware money serializer.\n\nWhile the statement is open the block is an **estimate**: `net`, `gross`\nand `total` carry the estimated net sum and `vat` and `withholding_tax` are\n`0`. The whole object is `null` when an open statement carries line items\nin more than one currency, since no single sum can be given then.\n",
"properties": {
"net": {
"type": "integer",
"description": "Net sum in munits.",
"nullable": true,
"example": 4000
},
"net_currency": {
"type": "string",
"description": "ISO 4217 currency code of `net`.",
"nullable": true,
"example": "EUR"
},
"vat": {
"type": "integer",
"description": "VAT in munits.",
"nullable": true,
"example": 0
},
"vat_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"gross": {
"type": "integer",
"description": "Gross sum in munits.",
"nullable": true,
"example": 4000
},
"gross_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"withholding_tax": {
"type": "integer",
"description": "Withholding tax in munits.",
"nullable": true,
"example": 0
},
"withholding_tax_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"total": {
"type": "integer",
"description": "Payable total in munits.",
"nullable": true,
"example": 4000
},
"total_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
}
}
},
"statement_run": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement run this statement belongs to, or null for a statement\ncreated by hand. A statement run is identified by the same string id on\nevery API version.\n",
"properties": {
"_id": {
"type": "string",
"example": "01JAV8M4XK9QZ2R7B0T3YH6E5N"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"example": "Tantiemen 2025/Q2"
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The CSV rendering of the statement, once it exists. Read-only; the file\nitself is fetched through `href`.\n",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
},
"required": []
}
Responses
Refer to the common response description: royalty_statement.
Refer to the common response description: bad_request.
GET /resource/v4/royalty_statements/{id}
Retrieve a single royalty statement
Description
Returns one statement. An id that is not a royalty statement — an order, for instance — returns 404, and one belonging to another realm returns 403.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | UUID of the royalty statement. |
Responses
Refer to the common response description: royalty_statement.
Refer to the common response description: not_found.
PUT /resource/v4/royalty_statements/{id}
Update a royalty statement
Description
Updates one statement. Despite being a PUT this is a partial
update: only the keys present in the body are applied and every omitted
key keeps its current value, so sending {} changes nothing.
Writable are name, period, invoice_date, business_partner,
statement_run, invoice_positions_grouped and invoiced. Everything
else — total, invoice_number, auto, cleared, realm, file_csv —
is read-only and ignored.
invoiced: true finalizes the statement and is applied last, after every
other field in the same request. invoiced: false on a finalized
statement is rejected with 400 Bad Request
(account::cannot_reopen_account); reopening goes through the reopen RPC.
A reference is given as an object carrying its _id
({"business_partner": {"_id": "<uuid>"}}), and statement_run: null
detaches the statement from its run.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | UUID of the royalty statement. |
Request body
{
"name": "Tantiemen 2025/Q2 (korrigiert)",
"invoice_positions_grouped": true
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One royalty statement — the account a business partner's royalties are booked\nonto, and the document that is rendered from it.\n\nInternally a royalty statement is an account of type `provision` (or\n`inter_realm`), which is why it shares its sub-resources with orders: line\nitems, files, correspondence and [invoice texts](/v4/account_texts/) all look\nthe same on both parents.\n\nA statement is **open** until it is finalized, and finalizing is what fixes\nthe numbers: `invoice_number` is assigned, the sums are written, and the\nsub-resources stop accepting writes. See `invoiced`.\n",
"properties": {
"_id": {
"type": "string",
"description": "UUID of the statement. This is the identifier on **both** v3 and v4 — the\nroyalty statement resource already addressed by UUID before v4 — so it is\nthe one v4 object whose `_id` did not change with the version.\n",
"example": "9c1e6d45-dafd-4698-b68f-a7cf5495ee23"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"description": "URLs of the statement and of each of its sub-resources.",
"properties": {
"self": {
"type": "string"
},
"line_items": {
"type": "string"
},
"summary": {
"type": "string"
},
"group_identifiers": {
"type": "string"
},
"files": {
"type": "string"
},
"correspondence": {
"type": "string"
},
"texts": {
"type": "string"
}
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"name": {
"type": "string",
"description": "Human-readable name of the statement, shown in listings and on the\nrendered document.\n",
"example": "Tantiemen 2025/Q2"
},
"period": {
"type": "string",
"description": "Technical description of the settlement period, as the statement run wrote\nit. Free text, empty when the statement was created by hand.\n",
"example": "2025/Q2"
},
"invoice_date": {
"type": "string",
"description": "Invoice date in YYYY-MM-DD format.",
"nullable": true,
"example": "2025-07-01"
},
"invoice_number": {
"type": "integer",
"description": "Invoice number, assigned when the statement is finalized. Null while the\nstatement is still open; read-only.\n",
"nullable": true,
"example": 918273
},
"invoiced": {
"type": "boolean",
"description": "Whether the statement has been finalized. Setting it to `true` in a `PUT`\n**finalizes the statement**: the sums are written and the invoice number is\nassigned. It cannot be set back to `false` — reopening is rejected with\n`400 Bad Request` (`account::cannot_reopen_account`) and is done through\nthe reopen RPC instead.\n\nOnce it is `true`, writes to the statement's line items and texts are\nrefused with `403 Permission denied`, so the rendered document and the data\nit was rendered from cannot diverge.\n"
},
"invoice_positions_grouped": {
"type": "boolean",
"description": "Whether line items are grouped by their reference on the rendered document\n(`false` prints every line item on its own).\n"
},
"auto": {
"type": "boolean",
"description": "Whether the statement was produced by the automatic royalty run rather than\ncreated by hand. Read-only.\n"
},
"cleared": {
"type": "boolean",
"description": "Whether the payout has been settled. Read-only."
},
"total": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement's sums.\n\n**This block is the one place in v4 that still carries the v3 money\nlayout**: a flat value in *munits* (1/100 of the currency unit) plus a\nsibling `<field>_currency`, rather than the\n[monetary value](/structured-fields/#monetary-value) object used everywhere else in\nv4 — including this resource's own line items and summary. It is built\nwithout going through the version-aware money serializer.\n\nWhile the statement is open the block is an **estimate**: `net`, `gross`\nand `total` carry the estimated net sum and `vat` and `withholding_tax` are\n`0`. The whole object is `null` when an open statement carries line items\nin more than one currency, since no single sum can be given then.\n",
"properties": {
"net": {
"type": "integer",
"description": "Net sum in munits.",
"nullable": true,
"example": 4000
},
"net_currency": {
"type": "string",
"description": "ISO 4217 currency code of `net`.",
"nullable": true,
"example": "EUR"
},
"vat": {
"type": "integer",
"description": "VAT in munits.",
"nullable": true,
"example": 0
},
"vat_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"gross": {
"type": "integer",
"description": "Gross sum in munits.",
"nullable": true,
"example": 4000
},
"gross_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"withholding_tax": {
"type": "integer",
"description": "Withholding tax in munits.",
"nullable": true,
"example": 0
},
"withholding_tax_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"total": {
"type": "integer",
"description": "Payable total in munits.",
"nullable": true,
"example": 4000
},
"total_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
}
}
},
"statement_run": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement run this statement belongs to, or null for a statement\ncreated by hand. A statement run is identified by the same string id on\nevery API version.\n",
"properties": {
"_id": {
"type": "string",
"example": "01JAV8M4XK9QZ2R7B0T3YH6E5N"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"example": "Tantiemen 2025/Q2"
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The CSV rendering of the statement, once it exists. Read-only; the file\nitself is fetched through `href`.\n",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
},
"required": []
}
Responses
Refer to the common response description: royalty_statement.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
DELETE /resource/v4/royalty_statements/{id}
Delete a royalty statement
Description
Removes the statement and everything hanging off it. Returns 204 with an empty body.
Returns 403 Permission denied once the statement has been finalized —
an issued statement is not deleted, it is corrected.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No | UUID of the royalty statement. |
Responses
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/summary
Retrieve the aggregated figures of a royalty statement
Description
Returns the statement's royalties grouped by product and month — the figures the summary page of the rendered document is built from.
This is a single object, not a paginated list, and it is computed on every request. Amounts are converted to EUR whatever currency the line items were booked in.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
{
"_id": 1787586506,
"overview": [
{
"product": {
"_id": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d",
"_legacy_id": 0,
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"months": [
{
"month": "2025-06",
"quantity": 12,
"royalties": {
"value": 42.23,
"currency": "EUR"
}
}
],
"sum": null
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "The statement's royalties aggregated per product and month — the figures the\nsummary page of the rendered document is built from.\n\nEvery line item of the statement is counted, grouped by its product and by the\nmonth of its settlement period. **Amounts are converted to EUR**, whatever\ncurrency the line items were booked in, so the sums here are comparable but do\nnot necessarily match a line item's own `net`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Legacy numeric id of the statement's account. Note this is *not* the\nstatement's `_id`, which is a UUID — this sub-resource has no identity of\nits own and reports the underlying account.\n",
"example": 1787586506
},
"overview": {
"type": "array",
"description": "One entry per product, plus one entry with `product: null` collecting the\nbookings that are not tied to a product. Ordered by the product's internal\nid.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Product ID",
"example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"months": {
"type": "array",
"description": "One entry per month that carries bookings, ascending.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"month": {
"type": "string",
"description": "The month, as YYYY-MM.",
"example": "2025-06"
},
"quantity": {
"type": "integer",
"description": "Units settled in that month.",
"example": 12
},
"royalties": {
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
}
}
},
"sum": {
"allOf": [
{
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
],
"description": "The product's royalties over all months listed."
}
}
}
}
},
"required": []
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/group_identifiers
Retrieve the retainer groups on a royalty statement
Description
Returns the distinct group_identifier values carried by the statement's
line items, with a human-readable label and whether the group holds a
retainer booking.
Unlike every other list in this resource, the response is not
paginated: it carries items and nothing else, because the groups are
derived from the line items rather than stored.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
{
"items": [
{
"_id": "retainer-2025-q2",
"name": "Garantiehonorar (DE01, retainer-2025-q2): v1387: Jugendliche und Internet-Communities",
"retainer": true
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "One retainer group present on the statement's line items.\n\nGroups are not a resource of their own — they exist because line items carry a\n`group_identifier` — so this is a distinct list of those values, with enough\ncontext to show them in a form.\n",
"properties": {
"_id": {
"type": "string",
"description": "The group identifier itself, as stored on the line item's\n`group_identifier` field. There is no numeric or UUID identity behind it.\n",
"example": "retainer-2025-q2"
},
"name": {
"type": "string",
"description": "Human-readable label built from the line items in the group — the\ndescription, business area and product of its retainer booking. Falls back\nto `_id` when the group carries no retainer booking to build one from.\n",
"example": "Garantiehonorar (DE01, retainer-2025-q2): v1387: Jugendliche und Internet-Communities"
},
"retainer": {
"type": "boolean",
"description": "Whether any line item in the group is a retainer booking. The old admin\nform offers only groups where this is `true`.\n"
}
},
"required": []
}
}
},
"required": [
"items"
]
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/line_items
Retrieve the line items of a royalty statement
Description
Returns the statement's bookings, paginated. description,
external_identifier_type and external_identifier_value are the
filterable fields; a filter on anything else returns 400.
Filtering on external_identifier_value alone matches only identifiers
that carry no type.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
description |
string | No | Filter line items by their description. | |
external_identifier_type |
string | No | Filter line items by the type of an external identifier. Equality only. | |
external_identifier_value |
string | No | Filter line items by the value of an external identifier. Equality only. Without `external_identifier_type`, only identifiers that carry no type are matched. | |
page |
integer | No | Page number, starting at 1. | |
page_size |
integer | No | Entries per page. Statements default to 25, sub-resources to 100. `display` is accepted as a legacy alias. | |
sort |
string | No | Sort field. Statements sort by `id` or `invoice_date`, both of which order by the account id; prefix with `-` for descending. |
Responses
Refer to the common response description: line_item_list.
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Refer to the common response description: not_found.
POST /resource/v4/royalty_statements/{royalty_statement_id}/line_items
Add a line item to a royalty statement
Description
Creates one booking on the statement. net is a monetary amount in major
units; quantity defaults to nothing and should be sent explicitly, since
total_net is derived from the two.
Either product or ean identifies what the booking is for, and each
resolves the other. A product reference takes the product's UUID on v4,
though its legacy integer id is accepted as well.
Returns 403 Permission denied if the statement has been finalized.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"description": "Tantiemen E-Book",
"quantity": 2,
"net": {
"value": 20.0,
"currency": "EUR"
},
"tax_details": {
"vat_rate_type": "reduced"
},
"chart_of_accounts": {
"account_number": "66020",
"business_area": null
},
"product": {
"_id": "a66da11e-e616-11ee-a221-00505699575c"
}
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One line item of a royalty statement — a single royalty booking, printed as one\nrow of the line-item table.\n\nInternally these are account transactions of type `provision`, which is why\nthey are negative in the booking system and positive here: the resource flips\nthe sign in both directions, so a payable royalty is a positive `net`.\n\nWrites are refused with `403 Permission denied` once the statement is\nfinalized (`invoiced: true`).\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the line item, and the value to put in the path of this\nsub-resource. Line items are **not** addressed by UUID, in v4 either — the\nroute accepts an integer only.\n",
"example": 8121
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"description": {
"type": "string",
"description": "What the booking is for, printed as the row's label. Required on create.\n",
"example": "Tantiemen E-Book"
},
"type": {
"type": "string",
"nullable": true,
"description": "Which kind of royalty this is, from the internal provision vocabulary\n(`retainer`, `manual`, `percentage`, `agent`, …). Free text rather than a\nclosed set, and null for a line item the UI created without one; `retainer`\nis the value the group identifiers sub-resource keys on.\n",
"example": "retainer"
},
"quantity": {
"type": "integer",
"description": "How many units the booking covers. `total_net` is `net` times this.\n",
"example": 2
},
"net": {
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
},
"total_net": {
"allOf": [
{
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
],
"description": "`net` times `quantity`, in the same currency. Read-only — it is derived,\nand sending it has no effect.\n"
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Product ID",
"example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"ean": {
"type": "string",
"nullable": true,
"description": "EAN of the product edition the booking refers to. Setting `ean` on a write\nresolves the product from it; setting `product` resolves the EAN from the\nproduct, so the two stay consistent whichever one is sent.\n",
"example": "9783638108638"
},
"group_identifier": {
"type": "string",
"nullable": true,
"description": "The retainer group this line item belongs to, or null. Line items sharing a\ngroup identifier are offset against each other when the retainer is settled;\nthe groups present on a statement are listed by the `group_identifiers`\nsub-resource. Send an empty string to clear it.\n",
"example": "retainer-2025-q2"
},
"render_period": {
"type": "string",
"nullable": true,
"description": "The settlement period the booking is printed under, in YYYY-MM-DD format.\nNull when it is not tied to a period.\n",
"example": "2025-06-30"
},
"tax_details": {
"type": "object",
"additionalProperties": false,
"properties": {
"vat_rate_type": {
"type": "string",
"nullable": true,
"description": "Which VAT rate applies to this booking. Resolved from the business\npartner's master data when the line item does not set it, so a `GET`\ncan return a value that was never written.\n",
"enum": [
"standard",
"reduced",
"zero"
],
"example": "reduced"
}
}
},
"chart_of_accounts": {
"type": "object",
"additionalProperties": false,
"description": "Where the booking lands in the ledger. Both fields fall back to the\nrealm's configuration when the line item does not set them, so a `GET` can\nreturn values that were never written; send an explicit `null` to clear\none.\n",
"properties": {
"account_number": {
"type": "string",
"nullable": true,
"example": "66020"
},
"business_area": {
"type": "string",
"nullable": true,
"example": "DE01"
}
}
},
"external_identifiers": {
"type": "array",
"description": "Identifiers of this booking in the systems it was imported from. Sending\nthe array replaces the whole set.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"nullable": true
},
"value": {
"type": "string",
"nullable": true
}
}
}
}
},
"required": []
}
Responses
Refer to the common response description: line_item.
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/line_items/{id}
Retrieve a single line item
Description
Returns one booking. A line item id that exists but belongs to a different statement returns 403, not 404 — the record is real, it is simply not reachable through that parent.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the line item. Line items have no UUID. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
PUT /resource/v4/royalty_statements/{royalty_statement_id}/line_items/{id}
Update a line item
Description
Updates one booking. Despite being a PUT this is a partial update:
only the keys present in the body are applied.
total_net is derived and ignored. Sending product: null or
ean: null detaches the product, and external_identifiers replaces the
whole set.
Returns 403 Permission denied if the statement has been finalized.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the line item. Line items have no UUID. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"net": {
"value": 22.5,
"currency": "EUR"
}
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One line item of a royalty statement — a single royalty booking, printed as one\nrow of the line-item table.\n\nInternally these are account transactions of type `provision`, which is why\nthey are negative in the booking system and positive here: the resource flips\nthe sign in both directions, so a payable royalty is a positive `net`.\n\nWrites are refused with `403 Permission denied` once the statement is\nfinalized (`invoiced: true`).\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the line item, and the value to put in the path of this\nsub-resource. Line items are **not** addressed by UUID, in v4 either — the\nroute accepts an integer only.\n",
"example": 8121
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"description": {
"type": "string",
"description": "What the booking is for, printed as the row's label. Required on create.\n",
"example": "Tantiemen E-Book"
},
"type": {
"type": "string",
"nullable": true,
"description": "Which kind of royalty this is, from the internal provision vocabulary\n(`retainer`, `manual`, `percentage`, `agent`, …). Free text rather than a\nclosed set, and null for a line item the UI created without one; `retainer`\nis the value the group identifiers sub-resource keys on.\n",
"example": "retainer"
},
"quantity": {
"type": "integer",
"description": "How many units the booking covers. `total_net` is `net` times this.\n",
"example": 2
},
"net": {
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
},
"total_net": {
"allOf": [
{
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
],
"description": "`net` times `quantity`, in the same currency. Read-only — it is derived,\nand sending it has no effect.\n"
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Product ID",
"example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"ean": {
"type": "string",
"nullable": true,
"description": "EAN of the product edition the booking refers to. Setting `ean` on a write\nresolves the product from it; setting `product` resolves the EAN from the\nproduct, so the two stay consistent whichever one is sent.\n",
"example": "9783638108638"
},
"group_identifier": {
"type": "string",
"nullable": true,
"description": "The retainer group this line item belongs to, or null. Line items sharing a\ngroup identifier are offset against each other when the retainer is settled;\nthe groups present on a statement are listed by the `group_identifiers`\nsub-resource. Send an empty string to clear it.\n",
"example": "retainer-2025-q2"
},
"render_period": {
"type": "string",
"nullable": true,
"description": "The settlement period the booking is printed under, in YYYY-MM-DD format.\nNull when it is not tied to a period.\n",
"example": "2025-06-30"
},
"tax_details": {
"type": "object",
"additionalProperties": false,
"properties": {
"vat_rate_type": {
"type": "string",
"nullable": true,
"description": "Which VAT rate applies to this booking. Resolved from the business\npartner's master data when the line item does not set it, so a `GET`\ncan return a value that was never written.\n",
"enum": [
"standard",
"reduced",
"zero"
],
"example": "reduced"
}
}
},
"chart_of_accounts": {
"type": "object",
"additionalProperties": false,
"description": "Where the booking lands in the ledger. Both fields fall back to the\nrealm's configuration when the line item does not set them, so a `GET` can\nreturn values that were never written; send an explicit `null` to clear\none.\n",
"properties": {
"account_number": {
"type": "string",
"nullable": true,
"example": "66020"
},
"business_area": {
"type": "string",
"nullable": true,
"example": "DE01"
}
}
},
"external_identifiers": {
"type": "array",
"description": "Identifiers of this booking in the systems it was imported from. Sending\nthe array replaces the whole set.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"nullable": true
},
"value": {
"type": "string",
"nullable": true
}
}
}
}
},
"required": []
}
Responses
Refer to the common response description: line_item.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
DELETE /resource/v4/royalty_statements/{royalty_statement_id}/line_items/{id}
Delete a line item
Description
Removes the booking permanently and re-estimates the statement's sums. Returns 204 with an empty body.
Returns 403 Permission denied if the statement has been finalized.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the line item. Line items have no UUID. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/files
Retrieve the files of a royalty statement
Description
Returns the files the system produced for the statement — the rendered PDF, its CSV, the mails that were sent — paginated and read-only. There is nothing to filter on.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
page |
integer | No | Page number, starting at 1. | |
page_size |
integer | No | Entries per page. Statements default to 25, sub-resources to 100. `display` is accepted as a legacy alias. |
Responses
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 9012,
"_version": "4.0",
"_links": {},
"file_name": "statement_918273.pdf",
"href": "string",
"type": "invoice_pdf",
"mime_type": "application/pdf",
"file_size": 51244,
"sha1": "string",
"timestamp": 1751362860,
"labels": [
"string"
],
"properties": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "One file belonging to an account — the rendered statement or invoice PDF, its\nCSV, or a mail that was sent. Files are produced by the system; this\nsub-resource is read-only.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the file, and the value to put in the path.",
"example": 9012
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object",
"description": "Note that `self` names the `orders` collection even for a royalty\nstatement's files, because both account types share one file resource.\n"
},
"file_name": {
"type": "string",
"description": "Original file name, and the name the download is served under.",
"example": "statement_918273.pdf"
},
"href": {
"type": "string",
"description": "Download URL. Fetching it streams the file with a `Content-Disposition`\nattachment header, rather than returning JSON.\n"
},
"type": {
"type": "string",
"nullable": true,
"description": "What the file is, in the account's own vocabulary.",
"example": "invoice_pdf"
},
"mime_type": {
"type": "string",
"nullable": true,
"example": "application/pdf"
},
"file_size": {
"type": "integer",
"description": "Size in bytes.",
"example": 51244
},
"sha1": {
"type": "string",
"nullable": true,
"description": "SHA-1 of the stored file."
},
"timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix timestamp of when the file was stored.",
"example": 1751362860
},
"labels": {
"type": "array",
"description": "Always empty for account files.",
"items": {
"type": "string"
}
},
"properties": {
"type": "object",
"description": "Always empty for account files."
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/files/{id}
Retrieve a single file's metadata
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the file. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
{
"_id": 9012,
"_version": "4.0",
"_links": {},
"file_name": "statement_918273.pdf",
"href": "string",
"type": "invoice_pdf",
"mime_type": "application/pdf",
"file_size": 51244,
"sha1": "string",
"timestamp": 1751362860,
"labels": [
"string"
],
"properties": {}
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One file belonging to an account — the rendered statement or invoice PDF, its\nCSV, or a mail that was sent. Files are produced by the system; this\nsub-resource is read-only.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the file, and the value to put in the path.",
"example": 9012
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object",
"description": "Note that `self` names the `orders` collection even for a royalty\nstatement's files, because both account types share one file resource.\n"
},
"file_name": {
"type": "string",
"description": "Original file name, and the name the download is served under.",
"example": "statement_918273.pdf"
},
"href": {
"type": "string",
"description": "Download URL. Fetching it streams the file with a `Content-Disposition`\nattachment header, rather than returning JSON.\n"
},
"type": {
"type": "string",
"nullable": true,
"description": "What the file is, in the account's own vocabulary.",
"example": "invoice_pdf"
},
"mime_type": {
"type": "string",
"nullable": true,
"example": "application/pdf"
},
"file_size": {
"type": "integer",
"description": "Size in bytes.",
"example": 51244
},
"sha1": {
"type": "string",
"nullable": true,
"description": "SHA-1 of the stored file."
},
"timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix timestamp of when the file was stored.",
"example": 1751362860
},
"labels": {
"type": "array",
"description": "Always empty for account files.",
"items": {
"type": "string"
}
},
"properties": {
"type": "object",
"description": "Always empty for account files."
}
},
"required": []
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/files/{id}/file
Download a file
Description
Streams the file itself, with the stored MIME type and a
Content-Disposition attachment header carrying its original name. This
is the URL the file's href points at, and the only endpoint here that
does not answer JSON.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the file. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
Schema of the response body
{
"type": "string",
"format": "binary"
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/correspondence
Retrieve the correspondence of a royalty statement
Description
Returns the documents sent, or scheduled to be sent, for the statement.
type is the only filterable field.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
page |
integer | No | Page number, starting at 1. | |
page_size |
integer | No | Entries per page. Statements default to 25, sub-resources to 100. `display` is accepted as a legacy alias. | |
type |
string | No | Filter correspondence by type, e.g. `statement`. Equality only. |
Responses
Refer to the common response description: correspondence_list.
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Refer to the common response description: not_found.
POST /resource/v4/royalty_statements/{royalty_statement_id}/correspondence
Schedule a correspondence for a royalty statement
Description
Creates a correspondence and schedules its documents. Rendering is
asynchronous: the response comes back with generated: false and no
files, and file_pdf / file_csv appear on a later GET.
Nothing is mailed yet — adding a recipient is what sends it. The authenticated admin user is recorded as the creator.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"type": "statement",
"attach_pdf": true,
"attach_csv": true
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One document sent, or to be sent, for an account — the statement or invoice PDF\nand the CSV that goes with it, together with the recipients it was mailed to.\n\nCreating a correspondence schedules the document: the PDF and CSV are rendered\nasynchronously, so `file_pdf` and `file_csv` stay null until `generated`\nbecomes `true`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the correspondence, and the value to put in the path. An\ninteger, in v4 too.\n",
"example": 4711
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"type": {
"type": "string",
"description": "Which document this is. Which values make sense depends on the parent: a\nroyalty statement carries `statement`, an order the invoice-side ones.\n",
"enum": [
"invoice",
"statement",
"delivery-slip",
"proforma-invoice",
"offer"
],
"example": "statement"
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the correspondence was created.",
"nullable": true,
"example": 1751362800
},
"generated": {
"type": "boolean",
"description": "Whether the documents have been rendered."
},
"generation_timestamp": {
"type": "integer",
"description": "Unix timestamp of when the documents were rendered.",
"nullable": true,
"example": 1751362860
},
"attach_pdf": {
"type": "boolean",
"description": "Whether the PDF is rendered and attached to the mail."
},
"attach_csv": {
"type": "boolean",
"description": "Whether the CSV is rendered and attached to the mail."
},
"file_pdf": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered PDF, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string",
"description": "Download URL of the file."
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered CSV, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"creator": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The admin user who created the correspondence, or null when it was created\nby an automatic run. Read-only.\n",
"properties": {
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
}
}
}
},
"required": []
}
Responses
Refer to the common response description: correspondence.
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/correspondence/{id}
Retrieve a single correspondence
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the correspondence. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
Refer to the common response description: correspondence.
Refer to the common response description: not_found.
PUT /resource/v4/royalty_statements/{royalty_statement_id}/correspondence/{id}
Update a correspondence
Description
Partial update of type, attach_pdf, attach_csv and generated.
Everything else is read-only.
Note this endpoint does not check whether the statement has been finalized.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric id of the correspondence. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"attach_csv": false
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One document sent, or to be sent, for an account — the statement or invoice PDF\nand the CSV that goes with it, together with the recipients it was mailed to.\n\nCreating a correspondence schedules the document: the PDF and CSV are rendered\nasynchronously, so `file_pdf` and `file_csv` stay null until `generated`\nbecomes `true`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the correspondence, and the value to put in the path. An\ninteger, in v4 too.\n",
"example": 4711
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"type": {
"type": "string",
"description": "Which document this is. Which values make sense depends on the parent: a\nroyalty statement carries `statement`, an order the invoice-side ones.\n",
"enum": [
"invoice",
"statement",
"delivery-slip",
"proforma-invoice",
"offer"
],
"example": "statement"
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the correspondence was created.",
"nullable": true,
"example": 1751362800
},
"generated": {
"type": "boolean",
"description": "Whether the documents have been rendered."
},
"generation_timestamp": {
"type": "integer",
"description": "Unix timestamp of when the documents were rendered.",
"nullable": true,
"example": 1751362860
},
"attach_pdf": {
"type": "boolean",
"description": "Whether the PDF is rendered and attached to the mail."
},
"attach_csv": {
"type": "boolean",
"description": "Whether the CSV is rendered and attached to the mail."
},
"file_pdf": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered PDF, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string",
"description": "Download URL of the file."
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered CSV, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"creator": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The admin user who created the correspondence, or null when it was created\nby an automatic run. Read-only.\n",
"properties": {
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
}
}
}
},
"required": []
}
Responses
Refer to the common response description: correspondence.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/correspondence/{correspondence_id}/recipients
Retrieve the recipients of a correspondence
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
correspondence_id |
integer | No | Numeric id of the correspondence. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
page |
integer | No | Page number, starting at 1. | |
page_size |
integer | No | Entries per page. Statements default to 25, sub-resources to 100. `display` is accepted as a legacy alias. |
Responses
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 8123,
"_version": "4.0",
"_links": {},
"email": "autorin@example.com",
"name": "Frau Sallenberg",
"processed": true,
"processed_timestamp": 1751362920,
"error": "string",
"file_email": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"bcc": [
"string"
]
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "One recipient of a correspondence. Adding a recipient is what actually sends\nthe document: the mail is dispatched asynchronously, and the outcome is\nreported back on this object through `processed` and `error`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the recipient, and the value to put in the path.",
"example": 8123
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"email": {
"type": "string",
"nullable": true,
"description": "The address the document is sent to.",
"example": "autorin@example.com"
},
"name": {
"type": "string",
"nullable": true,
"description": "Display name for the address.",
"example": "Frau Sallenberg"
},
"processed": {
"type": "boolean",
"description": "Whether the mail has been dispatched."
},
"processed_timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix timestamp of the dispatch.",
"example": 1751362920
},
"error": {
"type": "string",
"nullable": true,
"description": "Why the dispatch failed, or null. A recipient with an `error` was\nprocessed; the mail did not go out.\n"
},
"file_email": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The stored mail as it was sent, once it exists.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"bcc": {
"type": "array",
"deprecated": true,
"description": "Always empty. Kept so existing integrations do not break.",
"items": {
"type": "string"
}
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
Refer to the common response description: not_found.
POST /resource/v4/royalty_statements/{royalty_statement_id}/correspondence/{correspondence_id}/recipients
Add a recipient to a correspondence
Description
Adds an address and thereby sends the document to it. Dispatch is
asynchronous: the response comes back with processed: false, and a later
GET reports the outcome through processed, processed_timestamp and
error.
The same address can be added twice, and is then mailed twice.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
correspondence_id |
integer | No | Numeric id of the correspondence. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"email": "autorin@example.com"
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One recipient of a correspondence. Adding a recipient is what actually sends\nthe document: the mail is dispatched asynchronously, and the outcome is\nreported back on this object through `processed` and `error`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the recipient, and the value to put in the path.",
"example": 8123
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"email": {
"type": "string",
"nullable": true,
"description": "The address the document is sent to.",
"example": "autorin@example.com"
},
"name": {
"type": "string",
"nullable": true,
"description": "Display name for the address.",
"example": "Frau Sallenberg"
},
"processed": {
"type": "boolean",
"description": "Whether the mail has been dispatched."
},
"processed_timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix timestamp of the dispatch.",
"example": 1751362920
},
"error": {
"type": "string",
"nullable": true,
"description": "Why the dispatch failed, or null. A recipient with an `error` was\nprocessed; the mail did not go out.\n"
},
"file_email": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The stored mail as it was sent, once it exists.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"bcc": {
"type": "array",
"deprecated": true,
"description": "Always empty. Kept so existing integrations do not break.",
"items": {
"type": "string"
}
}
},
"required": []
}
Responses
{
"_id": 8123,
"_version": "4.0",
"_links": {},
"email": "autorin@example.com",
"name": "Frau Sallenberg",
"processed": true,
"processed_timestamp": 1751362920,
"error": "string",
"file_email": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"bcc": [
"string"
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One recipient of a correspondence. Adding a recipient is what actually sends\nthe document: the mail is dispatched asynchronously, and the outcome is\nreported back on this object through `processed` and `error`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the recipient, and the value to put in the path.",
"example": 8123
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"email": {
"type": "string",
"nullable": true,
"description": "The address the document is sent to.",
"example": "autorin@example.com"
},
"name": {
"type": "string",
"nullable": true,
"description": "Display name for the address.",
"example": "Frau Sallenberg"
},
"processed": {
"type": "boolean",
"description": "Whether the mail has been dispatched."
},
"processed_timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix timestamp of the dispatch.",
"example": 1751362920
},
"error": {
"type": "string",
"nullable": true,
"description": "Why the dispatch failed, or null. A recipient with an `error` was\nprocessed; the mail did not go out.\n"
},
"file_email": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The stored mail as it was sent, once it exists.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"bcc": {
"type": "array",
"deprecated": true,
"description": "Always empty. Kept so existing integrations do not break.",
"items": {
"type": "string"
}
}
},
"required": []
}
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
GET /resource/v4/royalty_statements/{royalty_statement_id}/correspondence/{correspondence_id}/recipients/{id}
Retrieve a single recipient
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
correspondence_id |
integer | No | Numeric id of the correspondence. | |
id |
integer | No | Numeric id of the recipient. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
{
"_id": 8123,
"_version": "4.0",
"_links": {},
"email": "autorin@example.com",
"name": "Frau Sallenberg",
"processed": true,
"processed_timestamp": 1751362920,
"error": "string",
"file_email": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"bcc": [
"string"
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One recipient of a correspondence. Adding a recipient is what actually sends\nthe document: the mail is dispatched asynchronously, and the outcome is\nreported back on this object through `processed` and `error`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the recipient, and the value to put in the path.",
"example": 8123
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"email": {
"type": "string",
"nullable": true,
"description": "The address the document is sent to.",
"example": "autorin@example.com"
},
"name": {
"type": "string",
"nullable": true,
"description": "Display name for the address.",
"example": "Frau Sallenberg"
},
"processed": {
"type": "boolean",
"description": "Whether the mail has been dispatched."
},
"processed_timestamp": {
"type": "integer",
"nullable": true,
"description": "Unix timestamp of the dispatch.",
"example": 1751362920
},
"error": {
"type": "string",
"nullable": true,
"description": "Why the dispatch failed, or null. A recipient with an `error` was\nprocessed; the mail did not go out.\n"
},
"file_email": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The stored mail as it was sent, once it exists.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"bcc": {
"type": "array",
"deprecated": true,
"description": "Always empty. Kept so existing integrations do not break.",
"items": {
"type": "string"
}
}
},
"required": []
}
Refer to the common response description: not_found.
Schemas
Account File
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Identifier of the file, and the value to put in the path. |
9012 |
_links |
object |
Note that |
|
_version |
string |
API version. |
4.0 |
file_name |
string |
Original file name, and the name the download is served under. |
statement_918273.pdf |
file_size |
integer |
Size in bytes. |
51244 |
href |
string |
Download URL. Fetching it streams the file with a |
|
labels |
Array<string> |
Always empty for account files. |
|
mime_type |
string| null | application/pdf |
|
properties |
object |
Always empty for account files. |
|
sha1 |
string| null |
SHA-1 of the stored file. |
|
timestamp |
integer| null |
Unix timestamp of when the file was stored. |
1751362860 |
type |
string| null |
What the file is, in the account's own vocabulary. |
invoice_pdf |
Correspondence
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Identifier of the correspondence, and the value to put in the path. An integer, in v4 too. |
4711 |
_links |
object | ||
_version |
string |
API version. |
4.0 |
attach_csv |
boolean |
Whether the CSV is rendered and attached to the mail. |
|
attach_pdf |
boolean |
Whether the PDF is rendered and attached to the mail. |
|
created |
integer| null |
Unix timestamp of when the correspondence was created. |
1751362800 |
creator |
Properties: business_partner| null |
The admin user who created the correspondence, or null when it was created by an automatic run. Read-only. |
|
creator.business_partner |
Properties: _id, _legacy_id, _links, screenname| null |
Reference to business partner |
{
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
} |
creator.business_partner._id |
string |
Business Partner ID |
eeee04ea-2752-40f5-a29d-3d67a77ba82c |
creator.business_partner._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
creator.business_partner._links |
object | ||
creator.business_partner.screenname |
string |
Display name of business partner |
Michael Scarn |
file_csv |
Properties: _id, _links, file_name, href| null |
The rendered CSV, or null while it does not exist yet. |
|
file_csv._id |
integer | ||
file_csv._links |
object | ||
file_csv.file_name |
string | ||
file_csv.href |
string | ||
file_pdf |
Properties: _id, _links, file_name, href| null |
The rendered PDF, or null while it does not exist yet. |
|
file_pdf._id |
integer | ||
file_pdf._links |
object | ||
file_pdf.file_name |
string | ||
file_pdf.href |
string |
Download URL of the file. |
|
generated |
boolean |
Whether the documents have been rendered. |
|
generation_timestamp |
integer| null |
Unix timestamp of when the documents were rendered. |
1751362860 |
type |
string |
Which document this is. Which values make sense depends on the parent: a
royalty statement carries |
statement |
Correspondence Recipient
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Identifier of the recipient, and the value to put in the path. |
8123 |
_links |
object | ||
_version |
string |
API version. |
4.0 |
bcc |
Array<string> |
Always empty. Kept so existing integrations do not break. |
|
email |
string| null |
The address the document is sent to. |
autorin@example.com |
error |
string| null |
Why the dispatch failed, or null. A recipient with an |
|
file_email |
Properties: _id, _links, file_name, href| null |
The stored mail as it was sent, once it exists. |
|
file_email._id |
integer | ||
file_email._links |
object | ||
file_email.file_name |
string | ||
file_email.href |
string | ||
name |
string| null |
Display name for the address. |
Frau Sallenberg |
processed |
boolean |
Whether the mail has been dispatched. |
|
processed_timestamp |
integer| null |
Unix timestamp of the dispatch. |
1751362920 |
Royalty Statement
| Name | Type | Description | Example |
|---|---|---|---|
_id |
string |
UUID of the statement. This is the identifier on both v3 and v4 — the
royalty statement resource already addressed by UUID before v4 — so it is
the one v4 object whose |
9c1e6d45-dafd-4698-b68f-a7cf5495ee23 |
_links |
Properties: self, line_items, summary, group_identifiers, files, correspondence, texts |
URLs of the statement and of each of its sub-resources. |
|
_links.self |
string | ||
_links.line_items |
string | ||
_links.summary |
string | ||
_links.group_identifiers |
string | ||
_links.files |
string | ||
_links.correspondence |
string | ||
_links.texts |
string | ||
_version |
string |
API version. |
4.0 |
auto |
boolean |
Whether the statement was produced by the automatic royalty run rather than created by hand. Read-only. |
|
business_partner |
Properties: _id, _legacy_id, _links, screenname| null |
Reference to business partner |
{
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
} |
business_partner._id |
string |
Business Partner ID |
eeee04ea-2752-40f5-a29d-3d67a77ba82c |
business_partner._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
business_partner._links |
object | ||
business_partner.screenname |
string |
Display name of business partner |
Michael Scarn |
cleared |
boolean |
Whether the payout has been settled. Read-only. |
|
file_csv |
Properties: _id, _links, file_name, href| null |
The CSV rendering of the statement, once it exists. Read-only; the file
itself is fetched through |
|
file_csv._id |
integer | ||
file_csv._links |
object | ||
file_csv.file_name |
string | ||
file_csv.href |
string | ||
invoice_date |
string| null |
Invoice date in YYYY-MM-DD format. |
2025-07-01 |
invoice_number |
integer| null |
Invoice number, assigned when the statement is finalized. Null while the statement is still open; read-only. |
918273 |
invoice_positions_grouped |
boolean |
Whether line items are grouped by their reference on the rendered document
( |
|
invoiced |
boolean |
Whether the statement has been finalized. Setting it to Once it is |
|
name |
string |
Human-readable name of the statement, shown in listings and on the rendered document. |
Tantiemen 2025/Q2 |
period |
string |
Technical description of the settlement period, as the statement run wrote it. Free text, empty when the statement was created by hand. |
2025/Q2 |
realm |
Properties: _id, _legacy_id, _links, name, screenname |
Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association. |
{
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
} |
realm._id |
string |
Realm ID |
297fc359-cac6-4c0a-a7db-aaee70c075f2 |
realm._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
realm._links |
object | ||
realm.name |
string |
Name of the realm |
zeilenquarz |
realm.screenname |
string |
Screenname of the realm |
Zeilenquarz Verlagsgruppe |
statement_run |
Properties: _id, _links, name| null |
The statement run this statement belongs to, or null for a statement created by hand. A statement run is identified by the same string id on every API version. |
|
statement_run._id |
string | 01JAV8M4XK9QZ2R7B0T3YH6E5N |
|
statement_run._links |
object | ||
statement_run.name |
string | Tantiemen 2025/Q2 |
|
total |
Properties: net, net_currency, vat, vat_currency, gross, gross_currency, withholding_tax, withholding_tax_currency, total, total_currency| null |
The statement's sums. This block is the one place in v4 that still carries the v3 money
layout: a flat value in munits (1/100 of the currency unit) plus a
sibling While the statement is open the block is an estimate: |
|
total.net |
integer| null |
Net sum in munits. |
4000 |
total.net_currency |
string| null |
ISO 4217 currency code of |
EUR |
total.vat |
integer| null |
VAT in munits. |
0 |
total.vat_currency |
string| null | EUR |
|
total.gross |
integer| null |
Gross sum in munits. |
4000 |
total.gross_currency |
string| null | EUR |
|
total.withholding_tax |
integer| null |
Withholding tax in munits. |
0 |
total.withholding_tax_currency |
string| null | EUR |
|
total.total |
integer| null |
Payable total in munits. |
4000 |
total.total_currency |
string| null | EUR |
Royalty Statement Group Identifier
| Name | Type | Description | Example |
|---|---|---|---|
_id |
string |
The group identifier itself, as stored on the line item's
|
retainer-2025-q2 |
name |
string |
Human-readable label built from the line items in the group — the
description, business area and product of its retainer booking. Falls back
to |
Garantiehonorar (DE01, retainer-2025-q2): v1387: Jugendliche und Internet-Communities |
retainer |
boolean |
Whether any line item in the group is a retainer booking. The old admin
form offers only groups where this is |
Royalty Statement Line Item
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Identifier of the line item, and the value to put in the path of this sub-resource. Line items are not addressed by UUID, in v4 either — the route accepts an integer only. |
8121 |
_version |
string |
API version. |
4.0 |
chart_of_accounts |
Properties: account_number, business_area |
Where the booking lands in the ledger. Both fields fall back to the
realm's configuration when the line item does not set them, so a |
|
chart_of_accounts.account_number |
string| null | 66020 |
|
chart_of_accounts.business_area |
string| null | DE01 |
|
description |
string |
What the booking is for, printed as the row's label. Required on create. |
Tantiemen E-Book |
ean |
string| null |
EAN of the product edition the booking refers to. Setting |
9783638108638 |
external_identifiers |
Array<Properties: type, value> |
Identifiers of this booking in the systems it was imported from. Sending the array replaces the whole set. |
|
external_identifiers[].type |
string| null | ||
external_identifiers[].value |
string| null | ||
group_identifier |
string| null |
The retainer group this line item belongs to, or null. Line items sharing a
group identifier are offset against each other when the retainer is settled;
the groups present on a statement are listed by the |
retainer-2025-q2 |
net |
Properties: value, currency| null |
Monetary Amount |
|
net.value |
number |
Value of the monetary amount |
42.23 |
net.currency |
string |
ISO 4217 currency code |
EUR |
product |
Properties: _id, _legacy_id, _links, title, eans, cover_url| null |
Reference to product |
|
product._id |
string |
Product ID |
5d2223ea-57bf-4f79-a06e-e1222ab81a5d |
product._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
product._links |
object | ||
product.title |
string |
Title of product |
Alice in Wonderland |
product.eans |
Array<> |
List of the EANs of the product |
|
product.cover_url |
string |
URL of cover thumbnail |
|
quantity |
integer |
How many units the booking covers. |
2 |
render_period |
string| null |
The settlement period the booking is printed under, in YYYY-MM-DD format. Null when it is not tied to a period. |
2025-06-30 |
tax_details |
Properties: vat_rate_type |
||
tax_details.vat_rate_type |
string| null |
Which VAT rate applies to this booking. Resolved from the business
partner's master data when the line item does not set it, so a |
reduced |
total_net |
|
||
type |
string| null |
Which kind of royalty this is, from the internal provision vocabulary
( |
retainer |
Royalty Statement Summary
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Legacy numeric id of the statement's account. Note this is not the
statement's |
1787586506 |
overview |
Array<Properties: product, months, sum> |
One entry per product, plus one entry with |
|
overview[].product |
Properties: _id, _legacy_id, _links, title, eans, cover_url| null |
Reference to product |
|
overview[].product._id |
string |
Product ID |
5d2223ea-57bf-4f79-a06e-e1222ab81a5d |
overview[].product._legacy_id |
integer |
Legacy integer identifier of this resource, kept so existing integrations can correlate their own records. |
|
overview[].product._links |
object | ||
overview[].product.title |
string |
Title of product |
Alice in Wonderland |
overview[].product.eans |
Array<> |
List of the EANs of the product |
|
overview[].product.cover_url |
string |
URL of cover thumbnail |
|
overview[].months |
Array<Properties: month, quantity, royalties> |
One entry per month that carries bookings, ascending. |
|
overview[].months[].month |
string |
The month, as YYYY-MM. |
2025-06 |
overview[].months[].quantity |
integer |
Units settled in that month. |
12 |
overview[].months[].royalties |
Properties: value, currency| null |
Monetary Amount |
|
overview[].months[].royalties.value |
number |
Value of the monetary amount |
42.23 |
overview[].months[].royalties.currency |
string |
ISO 4217 currency code |
EUR |
overview[].sum |
The product's royalties over all months listed. |
Common responses
This section describes common responses that are reused across operations.
royalty_statement
A single royalty statement
{
"_id": "9c1e6d45-dafd-4698-b68f-a7cf5495ee23",
"_version": "4.0",
"_links": {
"self": "string",
"line_items": "string",
"summary": "string",
"group_identifiers": "string",
"files": "string",
"correspondence": "string",
"texts": "string"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"name": "Tantiemen 2025/Q2",
"period": "2025/Q2",
"invoice_date": "2025-07-01",
"invoice_number": 918273,
"invoiced": true,
"invoice_positions_grouped": true,
"auto": true,
"cleared": true,
"total": {
"net": 4000,
"net_currency": "EUR",
"vat": 0,
"vat_currency": "EUR",
"gross": 4000,
"gross_currency": "EUR",
"withholding_tax": 0,
"withholding_tax_currency": "EUR",
"total": 4000,
"total_currency": "EUR"
},
"statement_run": {
"_id": "01JAV8M4XK9QZ2R7B0T3YH6E5N",
"_links": {},
"name": "Tantiemen 2025/Q2"
},
"file_csv": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
}
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One royalty statement — the account a business partner's royalties are booked\nonto, and the document that is rendered from it.\n\nInternally a royalty statement is an account of type `provision` (or\n`inter_realm`), which is why it shares its sub-resources with orders: line\nitems, files, correspondence and [invoice texts](/v4/account_texts/) all look\nthe same on both parents.\n\nA statement is **open** until it is finalized, and finalizing is what fixes\nthe numbers: `invoice_number` is assigned, the sums are written, and the\nsub-resources stop accepting writes. See `invoiced`.\n",
"properties": {
"_id": {
"type": "string",
"description": "UUID of the statement. This is the identifier on **both** v3 and v4 — the\nroyalty statement resource already addressed by UUID before v4 — so it is\nthe one v4 object whose `_id` did not change with the version.\n",
"example": "9c1e6d45-dafd-4698-b68f-a7cf5495ee23"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"description": "URLs of the statement and of each of its sub-resources.",
"properties": {
"self": {
"type": "string"
},
"line_items": {
"type": "string"
},
"summary": {
"type": "string"
},
"group_identifiers": {
"type": "string"
},
"files": {
"type": "string"
},
"correspondence": {
"type": "string"
},
"texts": {
"type": "string"
}
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"name": {
"type": "string",
"description": "Human-readable name of the statement, shown in listings and on the\nrendered document.\n",
"example": "Tantiemen 2025/Q2"
},
"period": {
"type": "string",
"description": "Technical description of the settlement period, as the statement run wrote\nit. Free text, empty when the statement was created by hand.\n",
"example": "2025/Q2"
},
"invoice_date": {
"type": "string",
"description": "Invoice date in YYYY-MM-DD format.",
"nullable": true,
"example": "2025-07-01"
},
"invoice_number": {
"type": "integer",
"description": "Invoice number, assigned when the statement is finalized. Null while the\nstatement is still open; read-only.\n",
"nullable": true,
"example": 918273
},
"invoiced": {
"type": "boolean",
"description": "Whether the statement has been finalized. Setting it to `true` in a `PUT`\n**finalizes the statement**: the sums are written and the invoice number is\nassigned. It cannot be set back to `false` — reopening is rejected with\n`400 Bad Request` (`account::cannot_reopen_account`) and is done through\nthe reopen RPC instead.\n\nOnce it is `true`, writes to the statement's line items and texts are\nrefused with `403 Permission denied`, so the rendered document and the data\nit was rendered from cannot diverge.\n"
},
"invoice_positions_grouped": {
"type": "boolean",
"description": "Whether line items are grouped by their reference on the rendered document\n(`false` prints every line item on its own).\n"
},
"auto": {
"type": "boolean",
"description": "Whether the statement was produced by the automatic royalty run rather than\ncreated by hand. Read-only.\n"
},
"cleared": {
"type": "boolean",
"description": "Whether the payout has been settled. Read-only."
},
"total": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement's sums.\n\n**This block is the one place in v4 that still carries the v3 money\nlayout**: a flat value in *munits* (1/100 of the currency unit) plus a\nsibling `<field>_currency`, rather than the\n[monetary value](/structured-fields/#monetary-value) object used everywhere else in\nv4 — including this resource's own line items and summary. It is built\nwithout going through the version-aware money serializer.\n\nWhile the statement is open the block is an **estimate**: `net`, `gross`\nand `total` carry the estimated net sum and `vat` and `withholding_tax` are\n`0`. The whole object is `null` when an open statement carries line items\nin more than one currency, since no single sum can be given then.\n",
"properties": {
"net": {
"type": "integer",
"description": "Net sum in munits.",
"nullable": true,
"example": 4000
},
"net_currency": {
"type": "string",
"description": "ISO 4217 currency code of `net`.",
"nullable": true,
"example": "EUR"
},
"vat": {
"type": "integer",
"description": "VAT in munits.",
"nullable": true,
"example": 0
},
"vat_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"gross": {
"type": "integer",
"description": "Gross sum in munits.",
"nullable": true,
"example": 4000
},
"gross_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"withholding_tax": {
"type": "integer",
"description": "Withholding tax in munits.",
"nullable": true,
"example": 0
},
"withholding_tax_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"total": {
"type": "integer",
"description": "Payable total in munits.",
"nullable": true,
"example": 4000
},
"total_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
}
}
},
"statement_run": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement run this statement belongs to, or null for a statement\ncreated by hand. A statement run is identified by the same string id on\nevery API version.\n",
"properties": {
"_id": {
"type": "string",
"example": "01JAV8M4XK9QZ2R7B0T3YH6E5N"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"example": "Tantiemen 2025/Q2"
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The CSV rendering of the statement, once it exists. Read-only; the file\nitself is fetched through `href`.\n",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
},
"required": []
}
royalty_statement_list
A list of royalty statements
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": "9c1e6d45-dafd-4698-b68f-a7cf5495ee23",
"_version": "4.0",
"_links": {
"self": "string",
"line_items": "string",
"summary": "string",
"group_identifiers": "string",
"files": "string",
"correspondence": "string",
"texts": "string"
},
"realm": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"name": "Tantiemen 2025/Q2",
"period": "2025/Q2",
"invoice_date": "2025-07-01",
"invoice_number": 918273,
"invoiced": true,
"invoice_positions_grouped": true,
"auto": true,
"cleared": true,
"total": {
"net": 4000,
"net_currency": "EUR",
"vat": 0,
"vat_currency": "EUR",
"gross": 4000,
"gross_currency": "EUR",
"withholding_tax": 0,
"withholding_tax_currency": "EUR",
"total": 4000,
"total_currency": "EUR"
},
"statement_run": {
"_id": "01JAV8M4XK9QZ2R7B0T3YH6E5N",
"_links": {},
"name": "Tantiemen 2025/Q2"
},
"file_csv": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "One royalty statement — the account a business partner's royalties are booked\nonto, and the document that is rendered from it.\n\nInternally a royalty statement is an account of type `provision` (or\n`inter_realm`), which is why it shares its sub-resources with orders: line\nitems, files, correspondence and [invoice texts](/v4/account_texts/) all look\nthe same on both parents.\n\nA statement is **open** until it is finalized, and finalizing is what fixes\nthe numbers: `invoice_number` is assigned, the sums are written, and the\nsub-resources stop accepting writes. See `invoiced`.\n",
"properties": {
"_id": {
"type": "string",
"description": "UUID of the statement. This is the identifier on **both** v3 and v4 — the\nroyalty statement resource already addressed by UUID before v4 — so it is\nthe one v4 object whose `_id` did not change with the version.\n",
"example": "9c1e6d45-dafd-4698-b68f-a7cf5495ee23"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"description": "URLs of the statement and of each of its sub-resources.",
"properties": {
"self": {
"type": "string"
},
"line_items": {
"type": "string"
},
"summary": {
"type": "string"
},
"group_identifiers": {
"type": "string"
},
"files": {
"type": "string"
},
"correspondence": {
"type": "string"
},
"texts": {
"type": "string"
}
}
},
"realm": {
"type": "object",
"description": "Reference to the realm which owns this object. A realm is a general term for the organisation whose data this is: usually a publishing house, but it may equally be a publishing group, or another kind of organisation or association.",
"example": {
"_id": "297fc359-cac6-4c0a-a7db-aaee70c075f2",
"_legacy_id": 7,
"name": "zeilenquarz",
"screenname": "Zeilenquarz Verlagsgruppe"
},
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Realm ID",
"example": "297fc359-cac6-4c0a-a7db-aaee70c075f2"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "zeilenquarz"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "Zeilenquarz Verlagsgruppe"
}
},
"required": [
"_id"
]
},
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
},
"name": {
"type": "string",
"description": "Human-readable name of the statement, shown in listings and on the\nrendered document.\n",
"example": "Tantiemen 2025/Q2"
},
"period": {
"type": "string",
"description": "Technical description of the settlement period, as the statement run wrote\nit. Free text, empty when the statement was created by hand.\n",
"example": "2025/Q2"
},
"invoice_date": {
"type": "string",
"description": "Invoice date in YYYY-MM-DD format.",
"nullable": true,
"example": "2025-07-01"
},
"invoice_number": {
"type": "integer",
"description": "Invoice number, assigned when the statement is finalized. Null while the\nstatement is still open; read-only.\n",
"nullable": true,
"example": 918273
},
"invoiced": {
"type": "boolean",
"description": "Whether the statement has been finalized. Setting it to `true` in a `PUT`\n**finalizes the statement**: the sums are written and the invoice number is\nassigned. It cannot be set back to `false` — reopening is rejected with\n`400 Bad Request` (`account::cannot_reopen_account`) and is done through\nthe reopen RPC instead.\n\nOnce it is `true`, writes to the statement's line items and texts are\nrefused with `403 Permission denied`, so the rendered document and the data\nit was rendered from cannot diverge.\n"
},
"invoice_positions_grouped": {
"type": "boolean",
"description": "Whether line items are grouped by their reference on the rendered document\n(`false` prints every line item on its own).\n"
},
"auto": {
"type": "boolean",
"description": "Whether the statement was produced by the automatic royalty run rather than\ncreated by hand. Read-only.\n"
},
"cleared": {
"type": "boolean",
"description": "Whether the payout has been settled. Read-only."
},
"total": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement's sums.\n\n**This block is the one place in v4 that still carries the v3 money\nlayout**: a flat value in *munits* (1/100 of the currency unit) plus a\nsibling `<field>_currency`, rather than the\n[monetary value](/structured-fields/#monetary-value) object used everywhere else in\nv4 — including this resource's own line items and summary. It is built\nwithout going through the version-aware money serializer.\n\nWhile the statement is open the block is an **estimate**: `net`, `gross`\nand `total` carry the estimated net sum and `vat` and `withholding_tax` are\n`0`. The whole object is `null` when an open statement carries line items\nin more than one currency, since no single sum can be given then.\n",
"properties": {
"net": {
"type": "integer",
"description": "Net sum in munits.",
"nullable": true,
"example": 4000
},
"net_currency": {
"type": "string",
"description": "ISO 4217 currency code of `net`.",
"nullable": true,
"example": "EUR"
},
"vat": {
"type": "integer",
"description": "VAT in munits.",
"nullable": true,
"example": 0
},
"vat_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"gross": {
"type": "integer",
"description": "Gross sum in munits.",
"nullable": true,
"example": 4000
},
"gross_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"withholding_tax": {
"type": "integer",
"description": "Withholding tax in munits.",
"nullable": true,
"example": 0
},
"withholding_tax_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
},
"total": {
"type": "integer",
"description": "Payable total in munits.",
"nullable": true,
"example": 4000
},
"total_currency": {
"type": "string",
"nullable": true,
"example": "EUR"
}
}
},
"statement_run": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The statement run this statement belongs to, or null for a statement\ncreated by hand. A statement run is identified by the same string id on\nevery API version.\n",
"properties": {
"_id": {
"type": "string",
"example": "01JAV8M4XK9QZ2R7B0T3YH6E5N"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"example": "Tantiemen 2025/Q2"
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The CSV rendering of the statement, once it exists. Read-only; the file\nitself is fetched through `href`.\n",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
line_item
A single line item
{
"_id": 8121,
"_version": "4.0",
"description": "Tantiemen E-Book",
"type": "retainer",
"quantity": 2,
"net": {
"value": 42.23,
"currency": "EUR"
},
"total_net": null,
"product": {
"_id": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d",
"_legacy_id": 0,
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"ean": "9783638108638",
"group_identifier": "retainer-2025-q2",
"render_period": "2025-06-30",
"tax_details": {
"vat_rate_type": "reduced"
},
"chart_of_accounts": {
"account_number": "66020",
"business_area": "DE01"
},
"external_identifiers": [
{
"type": "string",
"value": "string"
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One line item of a royalty statement — a single royalty booking, printed as one\nrow of the line-item table.\n\nInternally these are account transactions of type `provision`, which is why\nthey are negative in the booking system and positive here: the resource flips\nthe sign in both directions, so a payable royalty is a positive `net`.\n\nWrites are refused with `403 Permission denied` once the statement is\nfinalized (`invoiced: true`).\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the line item, and the value to put in the path of this\nsub-resource. Line items are **not** addressed by UUID, in v4 either — the\nroute accepts an integer only.\n",
"example": 8121
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"description": {
"type": "string",
"description": "What the booking is for, printed as the row's label. Required on create.\n",
"example": "Tantiemen E-Book"
},
"type": {
"type": "string",
"nullable": true,
"description": "Which kind of royalty this is, from the internal provision vocabulary\n(`retainer`, `manual`, `percentage`, `agent`, …). Free text rather than a\nclosed set, and null for a line item the UI created without one; `retainer`\nis the value the group identifiers sub-resource keys on.\n",
"example": "retainer"
},
"quantity": {
"type": "integer",
"description": "How many units the booking covers. `total_net` is `net` times this.\n",
"example": 2
},
"net": {
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
},
"total_net": {
"allOf": [
{
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
],
"description": "`net` times `quantity`, in the same currency. Read-only — it is derived,\nand sending it has no effect.\n"
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Product ID",
"example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"ean": {
"type": "string",
"nullable": true,
"description": "EAN of the product edition the booking refers to. Setting `ean` on a write\nresolves the product from it; setting `product` resolves the EAN from the\nproduct, so the two stay consistent whichever one is sent.\n",
"example": "9783638108638"
},
"group_identifier": {
"type": "string",
"nullable": true,
"description": "The retainer group this line item belongs to, or null. Line items sharing a\ngroup identifier are offset against each other when the retainer is settled;\nthe groups present on a statement are listed by the `group_identifiers`\nsub-resource. Send an empty string to clear it.\n",
"example": "retainer-2025-q2"
},
"render_period": {
"type": "string",
"nullable": true,
"description": "The settlement period the booking is printed under, in YYYY-MM-DD format.\nNull when it is not tied to a period.\n",
"example": "2025-06-30"
},
"tax_details": {
"type": "object",
"additionalProperties": false,
"properties": {
"vat_rate_type": {
"type": "string",
"nullable": true,
"description": "Which VAT rate applies to this booking. Resolved from the business\npartner's master data when the line item does not set it, so a `GET`\ncan return a value that was never written.\n",
"enum": [
"standard",
"reduced",
"zero"
],
"example": "reduced"
}
}
},
"chart_of_accounts": {
"type": "object",
"additionalProperties": false,
"description": "Where the booking lands in the ledger. Both fields fall back to the\nrealm's configuration when the line item does not set them, so a `GET` can\nreturn values that were never written; send an explicit `null` to clear\none.\n",
"properties": {
"account_number": {
"type": "string",
"nullable": true,
"example": "66020"
},
"business_area": {
"type": "string",
"nullable": true,
"example": "DE01"
}
}
},
"external_identifiers": {
"type": "array",
"description": "Identifiers of this booking in the systems it was imported from. Sending\nthe array replaces the whole set.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"nullable": true
},
"value": {
"type": "string",
"nullable": true
}
}
}
}
},
"required": []
}
line_item_list
A list of line items
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 8121,
"_version": "4.0",
"description": "Tantiemen E-Book",
"type": "retainer",
"quantity": 2,
"net": {
"value": 42.23,
"currency": "EUR"
},
"total_net": null,
"product": {
"_id": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d",
"_legacy_id": 0,
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"ean": "9783638108638",
"group_identifier": "retainer-2025-q2",
"render_period": "2025-06-30",
"tax_details": {
"vat_rate_type": "reduced"
},
"chart_of_accounts": {
"account_number": "66020",
"business_area": "DE01"
},
"external_identifiers": [
{
"type": "string",
"value": "string"
}
]
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "One line item of a royalty statement — a single royalty booking, printed as one\nrow of the line-item table.\n\nInternally these are account transactions of type `provision`, which is why\nthey are negative in the booking system and positive here: the resource flips\nthe sign in both directions, so a payable royalty is a positive `net`.\n\nWrites are refused with `403 Permission denied` once the statement is\nfinalized (`invoiced: true`).\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the line item, and the value to put in the path of this\nsub-resource. Line items are **not** addressed by UUID, in v4 either — the\nroute accepts an integer only.\n",
"example": 8121
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"description": {
"type": "string",
"description": "What the booking is for, printed as the row's label. Required on create.\n",
"example": "Tantiemen E-Book"
},
"type": {
"type": "string",
"nullable": true,
"description": "Which kind of royalty this is, from the internal provision vocabulary\n(`retainer`, `manual`, `percentage`, `agent`, …). Free text rather than a\nclosed set, and null for a line item the UI created without one; `retainer`\nis the value the group identifiers sub-resource keys on.\n",
"example": "retainer"
},
"quantity": {
"type": "integer",
"description": "How many units the booking covers. `total_net` is `net` times this.\n",
"example": 2
},
"net": {
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
},
"total_net": {
"allOf": [
{
"type": "object",
"description": "Monetary Amount",
"additionalProperties": false,
"nullable": true,
"properties": {
"value": {
"type": "number",
"description": "Value of the monetary amount",
"example": 42.23
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "EUR"
}
},
"required": [
"value",
"currency"
]
}
],
"description": "`net` times `quantity`, in the same currency. Read-only — it is derived,\nand sending it has no effect.\n"
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Product ID",
"example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"ean": {
"type": "string",
"nullable": true,
"description": "EAN of the product edition the booking refers to. Setting `ean` on a write\nresolves the product from it; setting `product` resolves the EAN from the\nproduct, so the two stay consistent whichever one is sent.\n",
"example": "9783638108638"
},
"group_identifier": {
"type": "string",
"nullable": true,
"description": "The retainer group this line item belongs to, or null. Line items sharing a\ngroup identifier are offset against each other when the retainer is settled;\nthe groups present on a statement are listed by the `group_identifiers`\nsub-resource. Send an empty string to clear it.\n",
"example": "retainer-2025-q2"
},
"render_period": {
"type": "string",
"nullable": true,
"description": "The settlement period the booking is printed under, in YYYY-MM-DD format.\nNull when it is not tied to a period.\n",
"example": "2025-06-30"
},
"tax_details": {
"type": "object",
"additionalProperties": false,
"properties": {
"vat_rate_type": {
"type": "string",
"nullable": true,
"description": "Which VAT rate applies to this booking. Resolved from the business\npartner's master data when the line item does not set it, so a `GET`\ncan return a value that was never written.\n",
"enum": [
"standard",
"reduced",
"zero"
],
"example": "reduced"
}
}
},
"chart_of_accounts": {
"type": "object",
"additionalProperties": false,
"description": "Where the booking lands in the ledger. Both fields fall back to the\nrealm's configuration when the line item does not set them, so a `GET` can\nreturn values that were never written; send an explicit `null` to clear\none.\n",
"properties": {
"account_number": {
"type": "string",
"nullable": true,
"example": "66020"
},
"business_area": {
"type": "string",
"nullable": true,
"example": "DE01"
}
}
},
"external_identifiers": {
"type": "array",
"description": "Identifiers of this booking in the systems it was imported from. Sending\nthe array replaces the whole set.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"nullable": true
},
"value": {
"type": "string",
"nullable": true
}
}
}
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
correspondence
A single correspondence
{
"_id": 4711,
"_version": "4.0",
"_links": {},
"type": "statement",
"created": 1751362800,
"generated": true,
"generation_timestamp": 1751362860,
"attach_pdf": true,
"attach_csv": true,
"file_pdf": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"file_csv": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"creator": {
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
}
}
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One document sent, or to be sent, for an account — the statement or invoice PDF\nand the CSV that goes with it, together with the recipients it was mailed to.\n\nCreating a correspondence schedules the document: the PDF and CSV are rendered\nasynchronously, so `file_pdf` and `file_csv` stay null until `generated`\nbecomes `true`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the correspondence, and the value to put in the path. An\ninteger, in v4 too.\n",
"example": 4711
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"type": {
"type": "string",
"description": "Which document this is. Which values make sense depends on the parent: a\nroyalty statement carries `statement`, an order the invoice-side ones.\n",
"enum": [
"invoice",
"statement",
"delivery-slip",
"proforma-invoice",
"offer"
],
"example": "statement"
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the correspondence was created.",
"nullable": true,
"example": 1751362800
},
"generated": {
"type": "boolean",
"description": "Whether the documents have been rendered."
},
"generation_timestamp": {
"type": "integer",
"description": "Unix timestamp of when the documents were rendered.",
"nullable": true,
"example": 1751362860
},
"attach_pdf": {
"type": "boolean",
"description": "Whether the PDF is rendered and attached to the mail."
},
"attach_csv": {
"type": "boolean",
"description": "Whether the CSV is rendered and attached to the mail."
},
"file_pdf": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered PDF, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string",
"description": "Download URL of the file."
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered CSV, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"creator": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The admin user who created the correspondence, or null when it was created\nby an automatic run. Read-only.\n",
"properties": {
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
}
}
}
},
"required": []
}
correspondence_list
A list of correspondence
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 4711,
"_version": "4.0",
"_links": {},
"type": "statement",
"created": 1751362800,
"generated": true,
"generation_timestamp": 1751362860,
"attach_pdf": true,
"attach_csv": true,
"file_pdf": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"file_csv": {
"_id": 0,
"_links": {},
"file_name": "string",
"href": "string"
},
"creator": {
"business_partner": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
}
}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"description": "One document sent, or to be sent, for an account — the statement or invoice PDF\nand the CSV that goes with it, together with the recipients it was mailed to.\n\nCreating a correspondence schedules the document: the PDF and CSV are rendered\nasynchronously, so `file_pdf` and `file_csv` stay null until `generated`\nbecomes `true`.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Identifier of the correspondence, and the value to put in the path. An\ninteger, in v4 too.\n",
"example": 4711
},
"_version": {
"type": "string",
"description": "API version.",
"example": "4.0"
},
"_links": {
"type": "object"
},
"type": {
"type": "string",
"description": "Which document this is. Which values make sense depends on the parent: a\nroyalty statement carries `statement`, an order the invoice-side ones.\n",
"enum": [
"invoice",
"statement",
"delivery-slip",
"proforma-invoice",
"offer"
],
"example": "statement"
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the correspondence was created.",
"nullable": true,
"example": 1751362800
},
"generated": {
"type": "boolean",
"description": "Whether the documents have been rendered."
},
"generation_timestamp": {
"type": "integer",
"description": "Unix timestamp of when the documents were rendered.",
"nullable": true,
"example": 1751362860
},
"attach_pdf": {
"type": "boolean",
"description": "Whether the PDF is rendered and attached to the mail."
},
"attach_csv": {
"type": "boolean",
"description": "Whether the CSV is rendered and attached to the mail."
},
"file_pdf": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered PDF, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string",
"description": "Download URL of the file."
}
}
},
"file_csv": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The rendered CSV, or null while it does not exist yet.",
"properties": {
"_id": {
"type": "integer"
},
"_links": {
"type": "object"
},
"file_name": {
"type": "string"
},
"href": {
"type": "string"
}
}
},
"creator": {
"type": "object",
"nullable": true,
"additionalProperties": false,
"description": "The admin user who created the correspondence, or null when it was created\nby an automatic run. Read-only.\n",
"properties": {
"business_partner": {
"type": "object",
"description": "Reference to business partner",
"example": {
"_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
"_legacy_id": 4242,
"screenname": "Michael Scarn"
},
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "string",
"description": "Business Partner ID",
"example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
},
"_legacy_id": {
"type": "integer",
"description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
},
"_links": {
"type": "object"
},
"screenname": {
"type": "string",
"description": "Display name of business partner",
"example": "Michael Scarn"
}
}
}
}
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
bad_request
Bad Request
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
not_found
Resource not found
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Common parameters
This section describes common parameters that are reused across operations.
id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No |
royalty_statement_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
royalty_statement_id |
path | string | No |
line_item_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | integer | No |
file_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | integer | No |
correspondence_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | integer | No |
correspondence_id_path
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
correspondence_id |
path | integer | No |
recipient_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | integer | No |
q
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
q |
query | string | No |
invoiced
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
invoiced |
query | boolean | No |
auto
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
auto |
query | boolean | No |
business_partner_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
business_partner_id |
query | integer | No |
statement_run_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
statement_run_id |
query | string | No |
line_item_description
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
description |
query | string | No |
external_identifier_type
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
external_identifier_type |
query | string | No |
external_identifier_value
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
external_identifier_value |
query | string | No |
correspondence_type
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
type |
query | string | No |
sort
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
sort |
query | string | No |
page
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
page |
query | integer | No |
page_size
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
page_size |
query | integer | No |