Invoice Texts v3
Sub-resource holding the text blocks that are written onto the PDF of an order invoice or of a royalty statement — the subject line, the salutation, the note explaining that royalties will be transferred or that the payout threshold was not reached, the closing.
The same object is reachable through both parents, with the same fields and the same behaviour:
/resource/v3/orders/{order_id}/textsfor orders and shopping carts/resource/v3/royalty_statements/{royalty_statement_id}/textsfor royalty statements
Texts are created from the realm's defaults when the account is created. This sub-resource exists so they can be corrected afterwards, before the document is issued.
Writes are only accepted while the account is still open. POST, PUT and DELETE
all return 403 Permission denied once the order or statement has been invoiced
(invoiced: true, i.e. account.status == finished), because the rendered PDF and the
text it was rendered from must not diverge. GET keeps working for the account's whole
lifetime.
Endpoints
GET /resource/v3/orders/{order_id}/texts
Retrieve the texts of an order
Description
Returns every text block of the order, paginated and ordered by _id. type is the
only field that can be filtered on — ?type=notes for the body text, for example.
See Resource Queries for the filter and pagination syntax.
An unknown order_id returns 404; an order belonging to another realm returns 403.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
order_id |
string | No | Numeric identifier of the order. |
Query parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
page |
integer | No | Page number, starting at 1. | |
page_size |
integer | No | Entries per page; defaults to 100. `display` is accepted as a legacy alias. | |
type |
string | No | Filter by text type, e.g. `notes` or `address-notes`. The only filterable field; any other name returns 400, as does an unknown type. |
Responses
Refer to the common response description: account_text_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/v3/orders/{order_id}/texts
Add a text to an order
Description
Creates one text block on the order. type is required; omitting it is rejected with
400 Bad Request. text may be omitted, which stores an empty text.
Returns 403 Permission denied if the order has already been invoiced.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
order_id |
string | No | Numeric identifier of the order. |
Request body
{
"type": "notes",
"text": "Der Rechnungsbetrag wurde bereits per Kreditkarte eingezogen."
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One text block rendered onto the PDF of an order invoice or of a royalty statement.\n\nA text is always owned by an account — an order or a royalty statement — and lives only\nas long as that account does. The set of blocks a document carries is created from the\nrealm's defaults when the account is created; this sub-resource is what makes them\neditable afterwards.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Numeric identifier of the text block, and the value to put in the path of this\nsub-resource on v3.\n",
"example": 918273
},
"_uuid": {
"type": "string",
"description": "UUID of the text block — the `_id` the same record has on the v4 and v5 endpoints.\n\nEmpty for a row that predates the `uuid` column and has not been written since; the\nvalue is assigned on the next write, and the one-time backfill run with the schema\nchange fills the rest.\n",
"example": "1125e821-9bfe-4deb-9ea8-72a82ef2891f"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "3.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "Canonical URL of this text. It names whichever of the two parent collections the\naccount is reachable through — `orders` for an order or shopping cart,\n`royalty_statements` for a royalty statement.\n",
"example": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
}
}
},
"text": {
"type": "string",
"description": "The text itself, as plain text. Line breaks are significant and are reproduced in the\nrendered document; there is no markup and no placeholder substitution — a text is\nwritten out exactly as stored, so any figures or account details it mentions have to\nbe filled in by whoever writes it.\n\nMay be empty, which renders nothing and is the way to suppress a block without\ndeleting it. The limit is 65535 bytes; a longer value is rejected with\n`400 Bad Request`.\n",
"example": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
},
"type": {
"type": "string",
"description": "Which block of the document this text fills. The vocabulary is a closed set — an\nunknown value is rejected with `400 Bad Request` — and is shared by invoices and\nroyalty statements, so not every type is meaningful on every document.\n\nNothing enforces one text per type: several texts of the same type are rendered one\nafter another, in ascending `_id` order, which is how a statement carries both a\npayout note and a threshold note under `notes`.\n",
"enum": [
"subject",
"greeting",
"heading",
"notes",
"header-notes",
"closing",
"address-notes"
],
"x-enum-descriptions": {
"subject": "The subject line, e.g. `Abrechnung Ihrer Tantiemen 2025/Q2`.",
"greeting": "The salutation opening the letter, e.g. `Sehr geehrte Frau Sallenberg,`.",
"heading": "Heading above the line-item table.",
"notes": "Free-form body text below the line-item table. The block that carries the payout or below-threshold explanation, and the one most often edited.",
"header-notes": "Free-form body text above the line-item table.",
"closing": "The closing, e.g. `Mit freundlichen Gruessen`, including the signature block.",
"address-notes": "Additional lines rendered inside the address field, e.g. a `c/o` line or a VAT note."
},
"example": "notes"
}
},
"required": []
}
Responses
Refer to the common response description: account_text.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
GET /resource/v3/orders/{order_id}/texts/{id}
Retrieve a single order text
Description
Returns one text block. A text id that exists but belongs to a different account returns 403, not 404 — the record is real, it is simply not reachable through that parent. An id that exists nowhere returns 404.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric identifier of the text block. | |
order_id |
string | No | Numeric identifier of the order. |
Responses
Refer to the common response description: account_text.
Refer to the common response description: not_found.
PUT /resource/v3/orders/{order_id}/texts/{id}
Update an order text
Description
Updates one text block. 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.
Returns 403 Permission denied if the order has already been invoiced.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric identifier of the text block. | |
order_id |
string | No | Numeric identifier of the order. |
Request body
{
"text": "Der Rechnungsbetrag wurde bereits per Kreditkarte eingezogen. Bitte ueberweisen Sie nichts."
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One text block rendered onto the PDF of an order invoice or of a royalty statement.\n\nA text is always owned by an account — an order or a royalty statement — and lives only\nas long as that account does. The set of blocks a document carries is created from the\nrealm's defaults when the account is created; this sub-resource is what makes them\neditable afterwards.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Numeric identifier of the text block, and the value to put in the path of this\nsub-resource on v3.\n",
"example": 918273
},
"_uuid": {
"type": "string",
"description": "UUID of the text block — the `_id` the same record has on the v4 and v5 endpoints.\n\nEmpty for a row that predates the `uuid` column and has not been written since; the\nvalue is assigned on the next write, and the one-time backfill run with the schema\nchange fills the rest.\n",
"example": "1125e821-9bfe-4deb-9ea8-72a82ef2891f"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "3.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "Canonical URL of this text. It names whichever of the two parent collections the\naccount is reachable through — `orders` for an order or shopping cart,\n`royalty_statements` for a royalty statement.\n",
"example": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
}
}
},
"text": {
"type": "string",
"description": "The text itself, as plain text. Line breaks are significant and are reproduced in the\nrendered document; there is no markup and no placeholder substitution — a text is\nwritten out exactly as stored, so any figures or account details it mentions have to\nbe filled in by whoever writes it.\n\nMay be empty, which renders nothing and is the way to suppress a block without\ndeleting it. The limit is 65535 bytes; a longer value is rejected with\n`400 Bad Request`.\n",
"example": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
},
"type": {
"type": "string",
"description": "Which block of the document this text fills. The vocabulary is a closed set — an\nunknown value is rejected with `400 Bad Request` — and is shared by invoices and\nroyalty statements, so not every type is meaningful on every document.\n\nNothing enforces one text per type: several texts of the same type are rendered one\nafter another, in ascending `_id` order, which is how a statement carries both a\npayout note and a threshold note under `notes`.\n",
"enum": [
"subject",
"greeting",
"heading",
"notes",
"header-notes",
"closing",
"address-notes"
],
"x-enum-descriptions": {
"subject": "The subject line, e.g. `Abrechnung Ihrer Tantiemen 2025/Q2`.",
"greeting": "The salutation opening the letter, e.g. `Sehr geehrte Frau Sallenberg,`.",
"heading": "Heading above the line-item table.",
"notes": "Free-form body text below the line-item table. The block that carries the payout or below-threshold explanation, and the one most often edited.",
"header-notes": "Free-form body text above the line-item table.",
"closing": "The closing, e.g. `Mit freundlichen Gruessen`, including the signature block.",
"address-notes": "Additional lines rendered inside the address field, e.g. a `c/o` line or a VAT note."
},
"example": "notes"
}
},
"required": []
}
Responses
Refer to the common response description: account_text.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
DELETE /resource/v3/orders/{order_id}/texts/{id}
Delete an order text
Description
Removes the text block permanently; there is no soft delete and no undo. Returns 204 with an empty body, and a second delete of the same id returns 404.
Returns 403 Permission denied if the order has already been invoiced.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric identifier of the text block. | |
order_id |
string | No | Numeric identifier of the order. |
Responses
Refer to the common response description: not_found.
GET /resource/v3/royalty_statements/{royalty_statement_id}/texts
Retrieve the texts of a royalty statement
Description
Returns every text block of the royalty statement, paginated and ordered by _id.
type is the only filterable field. See
Resource Queries for the filter and pagination syntax.
An unknown royalty_statement_id, or an account that is not a royalty statement,
returns 404; one belonging to another realm returns 403.
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; defaults to 100. `display` is accepted as a legacy alias. | |
type |
string | No | Filter by text type, e.g. `notes` or `address-notes`. The only filterable field; any other name returns 400, as does an unknown type. |
Responses
Refer to the common response description: account_text_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/v3/royalty_statements/{royalty_statement_id}/texts
Add a text to a royalty statement
Description
Creates one text block on the royalty statement. type is required; omitting it is
rejected with 400 Bad Request. text may be omitted, which stores an empty text.
Returns 403 Permission denied if the statement has already been invoiced.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"type": "notes",
"text": "Ihr Guthaben liegt unter der vereinbarten Auszahlungsgrenze von 50,00 EUR und wird auf die naechste Abrechnung vorgetragen."
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One text block rendered onto the PDF of an order invoice or of a royalty statement.\n\nA text is always owned by an account — an order or a royalty statement — and lives only\nas long as that account does. The set of blocks a document carries is created from the\nrealm's defaults when the account is created; this sub-resource is what makes them\neditable afterwards.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Numeric identifier of the text block, and the value to put in the path of this\nsub-resource on v3.\n",
"example": 918273
},
"_uuid": {
"type": "string",
"description": "UUID of the text block — the `_id` the same record has on the v4 and v5 endpoints.\n\nEmpty for a row that predates the `uuid` column and has not been written since; the\nvalue is assigned on the next write, and the one-time backfill run with the schema\nchange fills the rest.\n",
"example": "1125e821-9bfe-4deb-9ea8-72a82ef2891f"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "3.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "Canonical URL of this text. It names whichever of the two parent collections the\naccount is reachable through — `orders` for an order or shopping cart,\n`royalty_statements` for a royalty statement.\n",
"example": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
}
}
},
"text": {
"type": "string",
"description": "The text itself, as plain text. Line breaks are significant and are reproduced in the\nrendered document; there is no markup and no placeholder substitution — a text is\nwritten out exactly as stored, so any figures or account details it mentions have to\nbe filled in by whoever writes it.\n\nMay be empty, which renders nothing and is the way to suppress a block without\ndeleting it. The limit is 65535 bytes; a longer value is rejected with\n`400 Bad Request`.\n",
"example": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
},
"type": {
"type": "string",
"description": "Which block of the document this text fills. The vocabulary is a closed set — an\nunknown value is rejected with `400 Bad Request` — and is shared by invoices and\nroyalty statements, so not every type is meaningful on every document.\n\nNothing enforces one text per type: several texts of the same type are rendered one\nafter another, in ascending `_id` order, which is how a statement carries both a\npayout note and a threshold note under `notes`.\n",
"enum": [
"subject",
"greeting",
"heading",
"notes",
"header-notes",
"closing",
"address-notes"
],
"x-enum-descriptions": {
"subject": "The subject line, e.g. `Abrechnung Ihrer Tantiemen 2025/Q2`.",
"greeting": "The salutation opening the letter, e.g. `Sehr geehrte Frau Sallenberg,`.",
"heading": "Heading above the line-item table.",
"notes": "Free-form body text below the line-item table. The block that carries the payout or below-threshold explanation, and the one most often edited.",
"header-notes": "Free-form body text above the line-item table.",
"closing": "The closing, e.g. `Mit freundlichen Gruessen`, including the signature block.",
"address-notes": "Additional lines rendered inside the address field, e.g. a `c/o` line or a VAT note."
},
"example": "notes"
}
},
"required": []
}
Responses
Refer to the common response description: account_text.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
GET /resource/v3/royalty_statements/{royalty_statement_id}/texts/{id}
Retrieve a single royalty statement text
Description
Returns one text block. A text id that exists but belongs to a different account returns 403, not 404. An id that exists nowhere returns 404.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric identifier of the text block. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
Refer to the common response description: account_text.
Refer to the common response description: not_found.
PUT /resource/v3/royalty_statements/{royalty_statement_id}/texts/{id}
Update a royalty statement text
Description
Updates one text block. 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.
Returns 403 Permission denied if the statement has already been invoiced.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric identifier of the text block. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Request body
{
"text": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"description": "One text block rendered onto the PDF of an order invoice or of a royalty statement.\n\nA text is always owned by an account — an order or a royalty statement — and lives only\nas long as that account does. The set of blocks a document carries is created from the\nrealm's defaults when the account is created; this sub-resource is what makes them\neditable afterwards.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Numeric identifier of the text block, and the value to put in the path of this\nsub-resource on v3.\n",
"example": 918273
},
"_uuid": {
"type": "string",
"description": "UUID of the text block — the `_id` the same record has on the v4 and v5 endpoints.\n\nEmpty for a row that predates the `uuid` column and has not been written since; the\nvalue is assigned on the next write, and the one-time backfill run with the schema\nchange fills the rest.\n",
"example": "1125e821-9bfe-4deb-9ea8-72a82ef2891f"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "3.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "Canonical URL of this text. It names whichever of the two parent collections the\naccount is reachable through — `orders` for an order or shopping cart,\n`royalty_statements` for a royalty statement.\n",
"example": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
}
}
},
"text": {
"type": "string",
"description": "The text itself, as plain text. Line breaks are significant and are reproduced in the\nrendered document; there is no markup and no placeholder substitution — a text is\nwritten out exactly as stored, so any figures or account details it mentions have to\nbe filled in by whoever writes it.\n\nMay be empty, which renders nothing and is the way to suppress a block without\ndeleting it. The limit is 65535 bytes; a longer value is rejected with\n`400 Bad Request`.\n",
"example": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
},
"type": {
"type": "string",
"description": "Which block of the document this text fills. The vocabulary is a closed set — an\nunknown value is rejected with `400 Bad Request` — and is shared by invoices and\nroyalty statements, so not every type is meaningful on every document.\n\nNothing enforces one text per type: several texts of the same type are rendered one\nafter another, in ascending `_id` order, which is how a statement carries both a\npayout note and a threshold note under `notes`.\n",
"enum": [
"subject",
"greeting",
"heading",
"notes",
"header-notes",
"closing",
"address-notes"
],
"x-enum-descriptions": {
"subject": "The subject line, e.g. `Abrechnung Ihrer Tantiemen 2025/Q2`.",
"greeting": "The salutation opening the letter, e.g. `Sehr geehrte Frau Sallenberg,`.",
"heading": "Heading above the line-item table.",
"notes": "Free-form body text below the line-item table. The block that carries the payout or below-threshold explanation, and the one most often edited.",
"header-notes": "Free-form body text above the line-item table.",
"closing": "The closing, e.g. `Mit freundlichen Gruessen`, including the signature block.",
"address-notes": "Additional lines rendered inside the address field, e.g. a `c/o` line or a VAT note."
},
"example": "notes"
}
},
"required": []
}
Responses
Refer to the common response description: account_text.
Refer to the common response description: bad_request.
Refer to the common response description: not_found.
DELETE /resource/v3/royalty_statements/{royalty_statement_id}/texts/{id}
Delete a royalty statement text
Description
Removes the text block permanently. Returns 204 with an empty body, and a second delete of the same id returns 404.
Returns 403 Permission denied if the statement has already been invoiced.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
integer | No | Numeric identifier of the text block. | |
royalty_statement_id |
string | No | UUID of the royalty statement. |
Responses
Refer to the common response description: not_found.
Schemas
Invoice Text
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Numeric identifier of the text block, and the value to put in the path of this sub-resource on v3. |
918273 |
_links |
Properties: self |
||
_links.self |
string |
Canonical URL of this text. It names whichever of the two parent collections the
account is reachable through — |
https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273 |
_uuid |
string |
UUID of the text block — the Empty for a row that predates the |
1125e821-9bfe-4deb-9ea8-72a82ef2891f |
_version |
string |
API version. |
3.0 |
text |
string |
The text itself, as plain text. Line breaks are significant and are reproduced in the rendered document; there is no markup and no placeholder substitution — a text is written out exactly as stored, so any figures or account details it mentions have to be filled in by whoever writes it. May be empty, which renders nothing and is the way to suppress a block without
deleting it. The limit is 65535 bytes; a longer value is rejected with
|
Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen. |
type |
string |
Which block of the document this text fills. The vocabulary is a closed set — an
unknown value is rejected with Nothing enforces one text per type: several texts of the same type are rendered one
after another, in ascending |
notes |
Common responses
This section describes common responses that are reused across operations.
account_text
A single text block
{
"_id": 918273,
"_uuid": "1125e821-9bfe-4deb-9ea8-72a82ef2891f",
"_version": "3.0",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
},
"text": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen.",
"type": "notes"
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"description": "One text block rendered onto the PDF of an order invoice or of a royalty statement.\n\nA text is always owned by an account — an order or a royalty statement — and lives only\nas long as that account does. The set of blocks a document carries is created from the\nrealm's defaults when the account is created; this sub-resource is what makes them\neditable afterwards.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Numeric identifier of the text block, and the value to put in the path of this\nsub-resource on v3.\n",
"example": 918273
},
"_uuid": {
"type": "string",
"description": "UUID of the text block — the `_id` the same record has on the v4 and v5 endpoints.\n\nEmpty for a row that predates the `uuid` column and has not been written since; the\nvalue is assigned on the next write, and the one-time backfill run with the schema\nchange fills the rest.\n",
"example": "1125e821-9bfe-4deb-9ea8-72a82ef2891f"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "3.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "Canonical URL of this text. It names whichever of the two parent collections the\naccount is reachable through — `orders` for an order or shopping cart,\n`royalty_statements` for a royalty statement.\n",
"example": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
}
}
},
"text": {
"type": "string",
"description": "The text itself, as plain text. Line breaks are significant and are reproduced in the\nrendered document; there is no markup and no placeholder substitution — a text is\nwritten out exactly as stored, so any figures or account details it mentions have to\nbe filled in by whoever writes it.\n\nMay be empty, which renders nothing and is the way to suppress a block without\ndeleting it. The limit is 65535 bytes; a longer value is rejected with\n`400 Bad Request`.\n",
"example": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
},
"type": {
"type": "string",
"description": "Which block of the document this text fills. The vocabulary is a closed set — an\nunknown value is rejected with `400 Bad Request` — and is shared by invoices and\nroyalty statements, so not every type is meaningful on every document.\n\nNothing enforces one text per type: several texts of the same type are rendered one\nafter another, in ascending `_id` order, which is how a statement carries both a\npayout note and a threshold note under `notes`.\n",
"enum": [
"subject",
"greeting",
"heading",
"notes",
"header-notes",
"closing",
"address-notes"
],
"x-enum-descriptions": {
"subject": "The subject line, e.g. `Abrechnung Ihrer Tantiemen 2025/Q2`.",
"greeting": "The salutation opening the letter, e.g. `Sehr geehrte Frau Sallenberg,`.",
"heading": "Heading above the line-item table.",
"notes": "Free-form body text below the line-item table. The block that carries the payout or below-threshold explanation, and the one most often edited.",
"header-notes": "Free-form body text above the line-item table.",
"closing": "The closing, e.g. `Mit freundlichen Gruessen`, including the signature block.",
"address-notes": "Additional lines rendered inside the address field, e.g. a `c/o` line or a VAT note."
},
"example": "notes"
}
},
"required": []
}
account_text_list
A list of text blocks
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 918273,
"_uuid": "1125e821-9bfe-4deb-9ea8-72a82ef2891f",
"_version": "3.0",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
},
"text": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen.",
"type": "notes"
}
]
}
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 text block rendered onto the PDF of an order invoice or of a royalty statement.\n\nA text is always owned by an account — an order or a royalty statement — and lives only\nas long as that account does. The set of blocks a document carries is created from the\nrealm's defaults when the account is created; this sub-resource is what makes them\neditable afterwards.\n",
"properties": {
"_id": {
"type": "integer",
"description": "Numeric identifier of the text block, and the value to put in the path of this\nsub-resource on v3.\n",
"example": 918273
},
"_uuid": {
"type": "string",
"description": "UUID of the text block — the `_id` the same record has on the v4 and v5 endpoints.\n\nEmpty for a row that predates the `uuid` column and has not been written since; the\nvalue is assigned on the next write, and the one-time backfill run with the schema\nchange fills the rest.\n",
"example": "1125e821-9bfe-4deb-9ea8-72a82ef2891f"
},
"_version": {
"type": "string",
"description": "API version.",
"example": "3.0"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"description": "Canonical URL of this text. It names whichever of the two parent collections the\naccount is reachable through — `orders` for an order or shopping cart,\n`royalty_statements` for a royalty statement.\n",
"example": "https://api.openpublishing.com/resource/v3/royalty_statements/8f1c4e0a-3d77-4a19-9c52-6b0e2a4f18d3/texts/918273"
}
}
},
"text": {
"type": "string",
"description": "The text itself, as plain text. Line breaks are significant and are reproduced in the\nrendered document; there is no markup and no placeholder substitution — a text is\nwritten out exactly as stored, so any figures or account details it mentions have to\nbe filled in by whoever writes it.\n\nMay be empty, which renders nothing and is the way to suppress a block without\ndeleting it. The limit is 65535 bytes; a longer value is rejected with\n`400 Bad Request`.\n",
"example": "Die Tantiemen werden in den naechsten Tagen auf das bei uns hinterlegte Konto ueberwiesen."
},
"type": {
"type": "string",
"description": "Which block of the document this text fills. The vocabulary is a closed set — an\nunknown value is rejected with `400 Bad Request` — and is shared by invoices and\nroyalty statements, so not every type is meaningful on every document.\n\nNothing enforces one text per type: several texts of the same type are rendered one\nafter another, in ascending `_id` order, which is how a statement carries both a\npayout note and a threshold note under `notes`.\n",
"enum": [
"subject",
"greeting",
"heading",
"notes",
"header-notes",
"closing",
"address-notes"
],
"x-enum-descriptions": {
"subject": "The subject line, e.g. `Abrechnung Ihrer Tantiemen 2025/Q2`.",
"greeting": "The salutation opening the letter, e.g. `Sehr geehrte Frau Sallenberg,`.",
"heading": "Heading above the line-item table.",
"notes": "Free-form body text below the line-item table. The block that carries the payout or below-threshold explanation, and the one most often edited.",
"header-notes": "Free-form body text above the line-item table.",
"closing": "The closing, e.g. `Mit freundlichen Gruessen`, including the signature block.",
"address-notes": "Additional lines rendered inside the address field, e.g. a `c/o` line or a VAT note."
},
"example": "notes"
}
},
"required": []
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
bad_request
Bad Request. Common causes: type missing on create; an unknown type; a text
longer than 65535 bytes.
{
"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.
order_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
order_id |
path | string | No |
royalty_statement_id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
royalty_statement_id |
path | string | No |
id
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | integer | No |
type_filter
| Name | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
type |
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 |