Raccoon API reference

Raccoon ERP API (1.0.0)

Multi-tenant SaaS REST API for Raccoon, the agentic cloud ERP for small and medium businesses: business partners, products, invoices, files and tax. Authentication uses JWT Bearer tokens.

Conventions

  • Resource paths are versioned and plural — /resource/v{n}/{objects}.
  • A link to another object is an embedded reference, never a bare id — { "_id", "_class", "_name" }. Only _id is required on input; _name is a read-only display label the API composes on output.
  • DELETE responses are always 204 No Content with an empty body — including soft-deletes, cancellations, and "reset to default" semantics. Clients that need the post-deletion state must re-fetch.

Auth

Get a proof-of-work challenge for registration

Returns a signed puzzle that POST /auth/register accepts once. Find a solution string such that SHA-256 over the UTF-8 bytes of challenge + solution starts with difficulty zero bits. Production requires a solved challenge on every registration. No request body.

Responses

Response Schema: application/json
challenge
required
string

Signed and single use. Send it back unchanged.

difficulty
required
integer

Leading zero bits the hash must have.

expires_at
required
integer

Unix seconds after which the challenge is refused.

Response samples

Content type
application/json
{
  • "challenge": "string",
  • "difficulty": 16,
  • "expires_at": 0
}

Register a new tenant and admin user

A 422 with error registration_proof_invalid means the proof-of-work was missing, wrong, expired or already used. Get a new challenge and solve it before sending again.

Request Body schema: application/json
required
name
required
string [ 1 .. 80 ] characters

The one name on the form, trimmed. At most 80 characters, one line of the letterhead. It is stored as the owner's last_name (the first_name stays empty) and names the tenant, its starter Company and the seeded letterhead.

admin_email
required
string <email>
admin_password
required
string <password> [ 8 .. 72 ] characters

At most 72 bytes in UTF-8, so fewer than 72 characters when it contains accents, symbols or emoji. A longer password is refused with 422.

country
required
string = 2 characters

ISO 3166-1 alpha-2 country code. Fixes the pricing region, the VAT country and the default currency. The starter Company and the tenant's billing address get this country and no street, city or postal code.

language
string or null
Enum: "en" "de" "fr" "es" "pt" null

The owner's UI language (ISO 639-1). When omitted or null, the first supported language in the request's Accept-Language header is used, else en. Portuguese is pt (Brazilian Portuguese). Sets the user's language only, not the tenant's i18n.default_language.

challenge
string or null <= 1000 characters

A challenge from POST /auth/registration-challenges. Required in production, together with solution. When sent, it is checked.

solution
string or null <= 64 characters

A string such that SHA-256 over challenge + solution starts with the challenge's difficulty zero bits.

Responses

Response Schema: application/json
required
object (ReferenceValue)

Stored value for a field of type "reference"

user_id
required
string
access_token
required
string
refresh_token
required
string
token_type
required
string
expires_in
required
integer
auth_source
required
string
Enum: "login" "api_key"

Indicates how this session was authenticated. login for email + password, api_key when the caller exchanged an API key for the token pair. The flag is propagated through refresh; clients use it to disable actions that must not chain off an API-key session (e.g. creating another API key).

Request samples

Content type
application/json
{
  • "name": "Amina Otieno",
  • "admin_email": "admin@acme.de",
  • "admin_password": "pa$$word",
  • "country": "KE",
  • "language": "en",
  • "challenge": "string",
  • "solution": "string"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "user_id": "usr_def456",
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "auth_source": "login"
}

Authenticate and obtain tokens

After too many failed logins on one email the account is locked for 15 to 30 minutes. A locked account answers exactly like a wrong password (401, same body), so the lock does not reveal whether the email is registered. A password reset lifts it.

Request Body schema: application/json
required
email
string <email>
password
string <password>
api_key
string

Raw API key string (rccn_{key_id}_{secret}). When present, email and password are ignored. The returned token pair carries auth_source: api_key.

Responses

Response Schema: application/json
required
object (ReferenceValue)

Stored value for a field of type "reference"

user_id
required
string
access_token
required
string
refresh_token
required
string
token_type
required
string
expires_in
required
integer
auth_source
required
string
Enum: "login" "api_key"

Indicates how this session was authenticated. login for email + password, api_key when the caller exchanged an API key for the token pair. The flag is propagated through refresh; clients use it to disable actions that must not chain off an API-key session (e.g. creating another API key).

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "api_key": "string"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "user_id": "usr_def456",
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "auth_source": "login"
}

Rotate refresh token and obtain new token pair

Request Body schema: application/json
required
refresh_token
required
string

Responses

Response Schema: application/json
required
object (ReferenceValue)

Stored value for a field of type "reference"

user_id
required
string
access_token
required
string
refresh_token
required
string
token_type
required
string
expires_in
required
integer
auth_source
required
string
Enum: "login" "api_key"

Indicates how this session was authenticated. login for email + password, api_key when the caller exchanged an API key for the token pair. The flag is propagated through refresh; clients use it to disable actions that must not chain off an API-key session (e.g. creating another API key).

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "user_id": "usr_def456",
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "auth_source": "login"
}

Revoke refresh token (logout)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Email a time-limited password-reset link

Always returns 200 regardless of whether email matches a registered, active user — this prevents callers from using the response to enumerate registered accounts.

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Consume a reset-link token and set a new password

Single-use: the token is invalidated on first use whether or not the password update succeeds. On success, every outstanding refresh token for the user is revoked.

Request Body schema: application/json
required
token
required
string

The signed, single-use token from the reset-link email.

new_password
required
string <password> [ 8 .. 72 ] characters

At most 72 bytes in UTF-8, so fewer than 72 characters when it contains accents, symbols or emoji. A longer password is refused with 422.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "new_password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

API Keys

List the calling user's API keys

Returns the API keys owned by the authenticated user (never another user's keys). The bcrypt hash is never returned — only safe metadata.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
required
Array of objects (ApiKeyResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a new API key for the calling user

The raw key string is returned in the key field exactly once and cannot be recovered. Only a bcrypt hash of the secret portion (salt embedded) is persisted.

Forbidden when the calling session was itself authenticated with an API key (auth_source == "api_key") — preventing privilege chaining. An API key inherits the privileges of the owning user, so the role of the resulting session matches the user's role.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Response Schema: application/json
key_id
required
string
key
required
string

The raw key string in the form rccn_{key_id}_{secret}. Pass this verbatim in POST /auth/login body field api_key to exchange it for a JWT pair (see LoginRequest).

name
required
string
created_at
required
integer
Reference (object) or null

Reference to the user who created the key.

Request samples

Content type
application/json
{
  • "name": "CI deploy key"
}

Response samples

Content type
application/json
{
  • "key_id": "a1b2c3d4e5f6",
  • "key": "rccn_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  • "name": "CI deploy key",
  • "created_at": 1748815200,
  • "created_by": {
    }
}

Get a single API key (metadata only)

Authorizations:
BearerAuth
path Parameters
key_id
required
string

Short identifier embedded in the raw key string.

Responses

Response Schema: application/json
key_id
required
string

Short identifier embedded in the raw key string.

name
required
string
created_at
required
integer

Unix epoch seconds.

last_used_at
integer or null

Unix epoch seconds of the most recent successful exchange of this API key for a JWT pair at POST /auth/auth. Stays unchanged for subsequent requests within the same JWT session.

Reference (object) or null

Reference to the user who created the key. Carries the user display name denormalized at creation time. Null when the creator could not be resolved.

Response samples

Content type
application/json
{
  • "key_id": "a1b2c3d4e5f6",
  • "name": "CI deploy key",
  • "created_at": 1748815200,
  • "last_used_at": 0,
  • "created_by": {
    }
}

Revoke an API key

Authorizations:
BearerAuth
path Parameters
key_id
required
string

Short identifier embedded in the raw key string.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List every API key in the tenant

The owner-facing audit surface. Returns every API key in the calling tenant, whoever owns it, each carrying a user reference to its owner. Owner role required — administrators manage only their own keys, through /resource/v1/api-keys.

Keys are never minted here: an owner cannot create a key on another user's behalf.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
required
Array of objects (TenantApiKeyResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Revoke any API key in the tenant

Revokes the key regardless of which user owns it — the route an owner uses to cut off a departed colleague's credential. The revocation is published as an api_key deletion event, so the audit trail records the acting owner.

Authorizations:
BearerAuth
path Parameters
key_id
required
string

Short identifier embedded in the raw key string.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Business Partners

List business partners (paginated)

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

partner_type
string
Enum: "person" "company"
status
string
Enum: "active" "inactive"
q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of any (BusinessPartnerResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a business partner

Authorizations:
BearerAuth
Request Body schema: application/json
required
partner_type
required
string
first_name
required
string non-empty
last_name
required
string non-empty
phone
string
mobile
string
email
string <email>
Array of objects (EmailAddress)

All e-mail addresses linked to this partner. Send {"email": "..."} plus any role flags; email_id is assigned server-side.

website
string <uri>
notes
string
customer_number
string

The tenant's own reference for this partner (DIN 5008 Kundennummer), copied onto the documents it is billed on.

purchase_order_reference
string or null

EN 16931 BT-13, the buyer's purchase order. Copied onto each new invoice and offer to this partner unless the create request sends its own; documents already written keep theirs.

status
string
Default: "active"
Enum: "active" "inactive"
language
string [ 2 .. 5 ] characters
Default: "en"
discount_percent
number [ 0 .. 100 ]
Default: 0

Per-partner discount applied to product list prices on Order-to-Cash documents. Defaults to 0 (no discount). 0 % is semantically the "no override" state.

payment_due_days
integer or null >= 0

Calendar days from order date to payment due date. null (or absent) means inherit default_payment_due_days from the partner type.

Reference (object) or null

Reference to the BP's preferred invoice (billing) address. Must point at an address belonging to this BP that has is_invoice_address: true. The server validates both invariants on write. null means no preferred address is set; the invoice form falls back to the first address with the matching role flag.

Reference (object) or null

Like preferred_invoice_address but for the shipping slot.

Reference (object) or null

Like preferred_invoice_address but for the service slot.

Reference (object) or null

Optional tenant-defined sales channel this partner belongs to. null means unassigned.

vat_partner_type
string
Default: "b2c"
Enum: "b2c" "b2b" "public_authority"

Buyer kind, and the first input to VAT regime resolution. b2b with a VIES-validated VAT-ID unlocks intra-EU reverse-charge. Distinct from partner_type (the person/company discriminator). The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource).

dedupe_key
string or null [ 1 .. 64 ] characters

Optional. A second create with the same key within the tenant does not create a second partner. The partner already created is returned unchanged; the repeated body is not compared with it, and only its shape is checked. A key already used for another kind of record is a 409.

type_id
string [ 1 .. 100 ] characters

The business-partner-class tenant type this partner is created under. Every partner has one. Omitted, the partner is created under the tenant's default business-partner type; that is a 422 when the tenant has several and marks none of them default.

schema_version
string or null

Type version. Omitted = latest.

object

Custom field values keyed by section field IDs.

salutation
string
salutation_code
string
Enum: "frau" "herr" "divers" "mme" "m" "ms" "mr" "mx"

Machine-readable salutation feeding a future formal-greeting helper (deferred Phase 3 invoice-text epic).

date_of_birth
string <date>
gender
string
Enum: "male" "female" "other" "unknown"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
type_id
required
string

The tenant type this partner was created under.

status
required
string
Enum: "active" "inactive"
language
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

required
Array of objects (EmailAddress)

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

required
object

self is the partner's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

Request samples

Content type
application/json
Example
{
  • "phone": "+49 30 123456",
  • "mobile": "+49 170 1234567",
  • "email": "user@example.com",
  • "email_addresses": [
    ],
  • "website": "http://example.com",
  • "notes": "string",
  • "customer_number": "string",
  • "purchase_order_reference": "string",
  • "status": "active",
  • "language": "de",
  • "discount_percent": 10,
  • "payment_due_days": 30,
  • "preferred_invoice_address": {
    },
  • "preferred_shipping_address": {
    },
  • "preferred_service_address": {
    },
  • "channel": {
    },
  • "vat_partner_type": "b2c",
  • "dedupe_key": "string",
  • "type_id": "customer",
  • "schema_version": "string",
  • "data": { },
  • "partner_type": "person",
  • "salutation": "Ms.",
  • "salutation_code": "ms",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "date_of_birth": "1985-03-15",
  • "gender": "male"
}

Response samples

Content type
application/json
Example
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "type_id": "string",
  • "status": "active",
  • "language": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c",
  • "created_by": {
    }
}

Get a business partner (includes embedded addresses)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
type_id
required
string

The tenant type this partner was created under.

status
required
string
Enum: "active" "inactive"
language
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

required
Array of objects (EmailAddress)

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

required
object

self is the partner's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

Response samples

Content type
application/json
Example
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "type_id": "string",
  • "status": "active",
  • "language": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c",
  • "created_by": {
    }
}

Replace a business partner (full update)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
phone
string
mobile
string
email
string <email>
Array of objects (EmailAddress)

Replaces the partner's whole e-mail list. email_id is assigned server-side for new entries and preserved for existing ones.

website
string <uri>
notes
string
customer_number
string
purchase_order_reference
string or null

EN 16931 BT-13. null clears it.

status
string
Enum: "active" "inactive"
language
string
salutation
string
first_name
string non-empty
last_name
string non-empty
date_of_birth
string <date>
gender
string
Enum: "male" "female" "other" "unknown"
company_name
string non-empty
legal_form
string
vat_partner_type
string
Enum: "b2c" "b2b" "public_authority"
type_id
string or null
schema_version
string or null
object
discount_percent
number [ 0 .. 100 ]
payment_due_days
integer or null >= 0
Reference (object) or null
Reference (object) or null
Reference (object) or null
Reference (object) or null

Tenant-defined sales channel, or null to unassign.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
type_id
required
string

The tenant type this partner was created under.

status
required
string
Enum: "active" "inactive"
language
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

required
Array of objects (EmailAddress)

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

required
object

self is the partner's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

Request samples

Content type
application/json
{
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "email_addresses": [
    ],
  • "website": "http://example.com",
  • "notes": "string",
  • "customer_number": "string",
  • "purchase_order_reference": "string",
  • "status": "active",
  • "language": "string",
  • "salutation": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "date_of_birth": "2019-08-24",
  • "gender": "male",
  • "company_name": "string",
  • "legal_form": "string",
  • "vat_partner_type": "b2c",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "discount_percent": 100,
  • "payment_due_days": 0,
  • "preferred_invoice_address": {
    },
  • "preferred_shipping_address": {
    },
  • "preferred_service_address": {
    },
  • "channel": {
    }
}

Response samples

Content type
application/json
Example
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "type_id": "string",
  • "status": "active",
  • "language": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c",
  • "created_by": {
    }
}

Partially update a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
phone
string
mobile
string
email
string <email>
Array of objects (EmailAddress)

Replaces the partner's whole e-mail list. email_id is assigned server-side for new entries and preserved for existing ones.

website
string <uri>
notes
string
customer_number
string
purchase_order_reference
string or null

EN 16931 BT-13. null clears it.

status
string
Enum: "active" "inactive"
language
string
salutation
string
first_name
string non-empty
last_name
string non-empty
date_of_birth
string <date>
gender
string
Enum: "male" "female" "other" "unknown"
company_name
string non-empty
legal_form
string
vat_partner_type
string
Enum: "b2c" "b2b" "public_authority"
type_id
string or null
schema_version
string or null
object
discount_percent
number [ 0 .. 100 ]
payment_due_days
integer or null >= 0
Reference (object) or null
Reference (object) or null
Reference (object) or null
Reference (object) or null

Tenant-defined sales channel, or null to unassign.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
type_id
required
string

The tenant type this partner was created under.

status
required
string
Enum: "active" "inactive"
language
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

required
Array of objects (EmailAddress)

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

required
object

self is the partner's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

Request samples

Content type
application/json
{
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "email_addresses": [
    ],
  • "website": "http://example.com",
  • "notes": "string",
  • "customer_number": "string",
  • "purchase_order_reference": "string",
  • "status": "active",
  • "language": "string",
  • "salutation": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "date_of_birth": "2019-08-24",
  • "gender": "male",
  • "company_name": "string",
  • "legal_form": "string",
  • "vat_partner_type": "b2c",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "discount_percent": 100,
  • "payment_due_days": 0,
  • "preferred_invoice_address": {
    },
  • "preferred_shipping_address": {
    },
  • "preferred_service_address": {
    },
  • "channel": {
    }
}

Response samples

Content type
application/json
Example
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "type_id": "string",
  • "status": "active",
  • "language": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c",
  • "created_by": {
    }
}

Soft-delete a business partner (sets status=inactive)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Grant login access to a person-type business partner (owner only)

Creates a user account linked to the business partner and sets its business_partner_role. Restricted to the tenant owner. Only person-type partners without existing login access are eligible.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
email
required
string <email>
password
required
string <password> [ 8 .. 72 ] characters

At most 72 bytes in UTF-8, so fewer than 72 characters when it contains accents, symbols or emoji. A longer password is refused with 422.

role
string
Default: "administrator"
Value: "administrator"

Responses

Response Schema: application/json
user_id
required
string
business_partner_id
required
string
role
required
string
Value: "administrator"
email
required
string <email>
business_partner_role
required
string
Value: "administrator"

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "role": "administrator"
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "business_partner_id": "string",
  • "role": "administrator",
  • "email": "user@example.com",
  • "business_partner_role": "administrator"
}

Revoke login access from a business partner (owner only)

Deactivates the linked user account and clears the partner's business_partner_role. Restricted to the tenant owner. The owner's own login cannot be revoked.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Products this partner was billed before

The products most recently billed to this partner, newest first and capped. Read off the partner's own invoice line items, so it reflects what was actually billed rather than a separately maintained list. Empty for a partner with no invoice history.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (ProductResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Addresses

List addresses for a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (AddressResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Add an address to a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
street_line_1
required
string non-empty
city
required
string non-empty
country_code
required
string = 2 characters

ISO 3166-1 alpha-2 country code

label
string

Free-text structural label (e.g. "HQ", "Munich warehouse"). Purely descriptive — has no behaviour.

is_invoice_address
boolean
Default: false

When true, this address is eligible to fill the invoice slot on invoices for this business partner. Auto-defaults to true for the very first address created on a BP (the freelancer-friendly default).

is_shipping_address
boolean
Default: false

When true, this address is eligible to fill the shipping slot on invoices for this business partner.

is_service_address
boolean
Default: false

When true, this address is eligible to fill the service slot on invoices for this business partner.

street_line_2
string
state_province
string
postal_code
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "label": "HQ",
  • "is_invoice_address": false,
  • "is_shipping_address": false,
  • "is_service_address": false,
  • "street_line_1": "Musterstraße 1",
  • "street_line_2": "Apt 2B",
  • "city": "Berlin",
  • "state_province": "Berlin",
  • "postal_code": "10115",
  • "country_code": "DE"
}

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a specific address

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Replace an address (full update)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6
Request Body schema: application/json
required
label
string
is_invoice_address
boolean
is_shipping_address
boolean
is_service_address
boolean
street_line_1
string
street_line_2
string
city
string
state_province
string
postal_code
string
country_code
string = 2 characters

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "label": "string",
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "street_line_2": "string",
  • "city": "string",
  • "state_province": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Partially update an address

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6
Request Body schema: application/json
required
label
string
is_invoice_address
boolean
is_shipping_address
boolean
is_service_address
boolean
street_line_1
string
street_line_2
string
city
string
state_province
string
postal_code
string
country_code
string = 2 characters

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "label": "string",
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "street_line_2": "string",
  • "city": "string",
  • "state_province": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete an address

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Products

List products (optionally filtered by project)

Authorizations:
BearerAuth
query Parameters
project_id
string
Example: project_id=prj_a1b2c3d4e5f6

Filter products by project ID

limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (ProductResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a product

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
Reference (object) or null

Optional project to assign this product to

Reference (object) or null

Optional tenant-defined sales channel to assign this product to

type_id
string [ 1 .. 100 ] characters

The product-class tenant type this product is created under. Every product has one. Omitted, the product is created under the tenant's default product type; that is a 422 when the tenant has several and marks none of them default.

schema_version
string [ 1 .. 50 ] characters
object
stocking_unit_of_measure
string or null <= 20 characters

Overrides the product type's inventory_config.stocking_unit_of_measure for this product. null (the default) inherits the type's unit.

vat_category
string or null
Enum: "S" "Z" "E" null

VAT category (UNCL 5305) of what the product supplies: S taxed, Z zero-rated, E exempt. Optional — omitted, the product stores none and follows its type: it takes the type's current recommendation, else the tenant default, and a later change to the type reaches it. The VAT rate is resolved per invoice.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

supply_kind
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

Whether the product is goods or a service. Omitted, the product follows its type's current default_supply_kind.

Array of objects (ProductPriceInput)

Inline price entries. Single-price mode (pricing_config with no flags enabled on the product type) accepts at most one entry with no scoping fields. Multi-dimension mode accepts N entries with the corresponding scoping fields populated. The service layer rejects rows whose scoping fields aren't gated by the relevant pricing_config flag.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the product's own resource URL, texts the collection of the texts it carries, prices the collection of its price rows. Further rels may be present; a client follows the ones it knows.

type_id
required
string
schema_version
required
string
name
required
string
required
object
stocking_unit_of_measure
required
string or null <= 20 characters

Overrides the product type's inventory_config.stocking_unit_of_measure for this product. null (the default) inherits the type's unit.

vat_category
required
string or null
Enum: "S" "Z" "E" null

The product's own VAT category (UNCL 5305); null when the product follows its type. What applies is effective_vat_category.

vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

The product's own supply kind; null when the product follows its type's default_supply_kind.

effective_vat_category
required
string
Enum: "S" "Z" "E"

Read-only, never stored. The VAT category that applies now: the product's own, else its type's current recommendation, else the tenant default. The per-invoice rate is resolved from it.

effective_vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Read-only. The rate class that applies now; set exactly when effective_vat_category is S.

effective_supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

Read-only. The supply kind that applies now: the product's own, else its type's current default_supply_kind; null when neither names one.

vat_category_source
required
string
Enum: "product" "type" "tenant_default"

Read-only. Where effective_vat_category comes from: the product's own choice, its type's recommendation, or the tenant default.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

required
Array of objects (ProductSaveWarning)
Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (ProductPrice)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Request samples

Content type
application/json
{
  • "project": {
    },
  • "channel": {
    },
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "stocking_unit_of_measure": "string",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "supply_kind": "goods",
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "stocking_unit_of_measure": "string",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "supply_kind": "goods",
  • "effective_vat_category": "S",
  • "effective_vat_rate_class": "standard",
  • "effective_supply_kind": "goods",
  • "vat_category_source": "product",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ],
  • "created_by": {
    },
  • "warnings": [
    ]
}

Get a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the product's own resource URL, texts the collection of the texts it carries, prices the collection of its price rows. Further rels may be present; a client follows the ones it knows.

type_id
required
string
schema_version
required
string
name
required
string
required
object
stocking_unit_of_measure
required
string or null <= 20 characters

Overrides the product type's inventory_config.stocking_unit_of_measure for this product. null (the default) inherits the type's unit.

vat_category
required
string or null
Enum: "S" "Z" "E" null

The product's own VAT category (UNCL 5305); null when the product follows its type. What applies is effective_vat_category.

vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

The product's own supply kind; null when the product follows its type's default_supply_kind.

effective_vat_category
required
string
Enum: "S" "Z" "E"

Read-only, never stored. The VAT category that applies now: the product's own, else its type's current recommendation, else the tenant default. The per-invoice rate is resolved from it.

effective_vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Read-only. The rate class that applies now; set exactly when effective_vat_category is S.

effective_supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

Read-only. The supply kind that applies now: the product's own, else its type's current default_supply_kind; null when neither names one.

vat_category_source
required
string
Enum: "product" "type" "tenant_default"

Read-only. Where effective_vat_category comes from: the product's own choice, its type's recommendation, or the tenant default.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (ProductPrice)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Response samples

Content type
application/json
{
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "stocking_unit_of_measure": "string",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "supply_kind": "goods",
  • "effective_vat_category": "S",
  • "effective_vat_rate_class": "standard",
  • "effective_supply_kind": "goods",
  • "vat_category_source": "product",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ],
  • "created_by": {
    }
}

Partially update a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
object
Reference (object) or null

Sales channel to assign, or null to unassign

stocking_unit_of_measure
string or null <= 20 characters

Stocking-unit override for this product. Omit to leave it unchanged; send null to fall back to the product type's unit.

vat_category
string or null
Enum: "S" "Z" "E" null

VAT category (UNCL 5305). Omit to leave unchanged. Sent, it takes vat_rate_class with it: set exactly when it is S. null clears the category and its rate class, and the product follows its type again.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S. Sent alone, it joins the stored category, which must be S; a product that follows its type has none, so a rate class sent alone to it is refused. null sent alone, without vat_category, changes nothing.

supply_kind
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

Omit to leave unchanged; null clears it, and the product follows its type's default_supply_kind again.

schema_version
string or null [ 1 .. 50 ] characters

Move the product to another version of its own type, even one that renamed the type's type_id. data is validated against that version. Omit or null to leave it unchanged.

Array of objects or null (ProductPriceInput)

Omit (or null) to leave the existing prices unchanged. Empty array to clear. Any non-empty list replaces the prices array.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the product's own resource URL, texts the collection of the texts it carries, prices the collection of its price rows. Further rels may be present; a client follows the ones it knows.

type_id
required
string
schema_version
required
string
name
required
string
required
object
stocking_unit_of_measure
required
string or null <= 20 characters

Overrides the product type's inventory_config.stocking_unit_of_measure for this product. null (the default) inherits the type's unit.

vat_category
required
string or null
Enum: "S" "Z" "E" null

The product's own VAT category (UNCL 5305); null when the product follows its type. What applies is effective_vat_category.

vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

The product's own supply kind; null when the product follows its type's default_supply_kind.

effective_vat_category
required
string
Enum: "S" "Z" "E"

Read-only, never stored. The VAT category that applies now: the product's own, else its type's current recommendation, else the tenant default. The per-invoice rate is resolved from it.

effective_vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Read-only. The rate class that applies now; set exactly when effective_vat_category is S.

effective_supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

Read-only. The supply kind that applies now: the product's own, else its type's current default_supply_kind; null when neither names one.

vat_category_source
required
string
Enum: "product" "type" "tenant_default"

Read-only. Where effective_vat_category comes from: the product's own choice, its type's recommendation, or the tenant default.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

required
Array of objects (ProductSaveWarning)
Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (ProductPrice)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Request samples

Content type
application/json
{
  • "name": "string",
  • "data": { },
  • "channel": {
    },
  • "stocking_unit_of_measure": "string",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "supply_kind": "goods",
  • "schema_version": "string",
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "stocking_unit_of_measure": "string",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "supply_kind": "goods",
  • "effective_vat_category": "S",
  • "effective_vat_rate_class": "standard",
  • "effective_supply_kind": "goods",
  • "vat_category_source": "product",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ],
  • "created_by": {
    },
  • "warnings": [
    ]
}

Delete a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Assign or unassign a product's project

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null

Project reference to assign, or null to unassign

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the product's own resource URL, texts the collection of the texts it carries, prices the collection of its price rows. Further rels may be present; a client follows the ones it knows.

type_id
required
string
schema_version
required
string
name
required
string
required
object
stocking_unit_of_measure
required
string or null <= 20 characters

Overrides the product type's inventory_config.stocking_unit_of_measure for this product. null (the default) inherits the type's unit.

vat_category
required
string or null
Enum: "S" "Z" "E" null

The product's own VAT category (UNCL 5305); null when the product follows its type. What applies is effective_vat_category.

vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

The product's own supply kind; null when the product follows its type's default_supply_kind.

effective_vat_category
required
string
Enum: "S" "Z" "E"

Read-only, never stored. The VAT category that applies now: the product's own, else its type's current recommendation, else the tenant default. The per-invoice rate is resolved from it.

effective_vat_rate_class
required
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Read-only. The rate class that applies now; set exactly when effective_vat_category is S.

effective_supply_kind
required
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

Read-only. The supply kind that applies now: the product's own, else its type's current default_supply_kind; null when neither names one.

vat_category_source
required
string
Enum: "product" "type" "tenant_default"

Read-only. Where effective_vat_category comes from: the product's own choice, its type's recommendation, or the tenant default.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (ProductPrice)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Request samples

Content type
application/json
{
  • "project": {
    }
}

Response samples

Content type
application/json
{
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "stocking_unit_of_measure": "string",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "supply_kind": "goods",
  • "effective_vat_category": "S",
  • "effective_vat_rate_class": "standard",
  • "effective_supply_kind": "goods",
  • "vat_category_source": "product",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ],
  • "created_by": {
    }
}

Append a price row to a product

Sub-resource sugar over the parent Product update. Single-price mode accepts at most one row across the product's lifetime — adding a second one returns 422 until the relevant pricing_config flag is enabled on the product type. Scoping fields (country_codes, channel, …) are rejected unless their gating flag is on.

The row is new by definition, so a body carrying _id is a 422 — the server assigns price ids. To change an existing row, address its own URL.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
required
object (MonetaryAmountInput)

Request-side counterpart of MonetaryAmount. Identical, except that amount also accepts a quoted decimal string — the encoding the precision contract above tells clients to use for sub-cent values, which the server's Pydantic coerces to an exact Decimal.

Responses always carry amount as a JSON number; use MonetaryAmount for those.

_id
string or null

Omitted means create; the server assigns a prc_… id. When present it must name a row already on that product, otherwise the request is a 422 (product.price_id_unknown, details.line_index naming the row). Ids are the server's; a client never chooses one.

_class
string or null
Enum: "price" null

Accepted on input but ignored — the server always assigns "price".

amount_is_gross
boolean or null

Whether amount includes VAT. Omitted, the tenant default.

vat_category
string or null
Enum: "S" "Z" "E" null
vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null
country_codes
Array of strings[ items = 2 characters ]
Reference (object) or null
valid_from
string or null <date>
valid_to
string or null <date>
is_campaign
boolean
Default: false
MonetaryAmountInput (object) or null
number or string
Default: 1
unit_of_measure
string
Default: "EA"
compute
object or null
priority
integer
Default: 0

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
required
object

self is the row's own resource URL, under the product that owns it. It survives an edit: a price id is the server's and is kept when a caller round-trips it.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

amount_is_gross
required
boolean

Whether amount includes VAT.

vat_category
required
string or null
Enum: "S" "Z" "E" null

VAT category (UNCL 5305) override for this row. Null inherits the Product-level vat_category and vat_rate_class. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "price",
  • "amount": {
    },
  • "amount_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "_links": {
    },
  • "amount": {
    },
  • "amount_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Get one price row

A price is an object with an id, so it answers at its own URL — the one every row carries as _links.self. 404 when this product does not hold that row, including when it belongs to another product.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
required
object

self is the row's own resource URL, under the product that owns it. It survives an edit: a price id is the server's and is kept when a caller round-trips it.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

amount_is_gross
required
boolean

Whether amount includes VAT.

vat_category
required
string or null
Enum: "S" "Z" "E" null

VAT category (UNCL 5305) override for this row. Null inherits the Product-level vat_category and vat_rate_class. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "_links": {
    },
  • "amount": {
    },
  • "amount_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Replace one price row

Full replace: the body is the new row contents; the price_id stays with the row across the swap so downstream snapshots (invoice lines, change logs) keep their back-link. A body _id that disagrees with the URL is a 422 rather than being silently overridden.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6
Request Body schema: application/json
required
required
object (MonetaryAmountInput)

Request-side counterpart of MonetaryAmount. Identical, except that amount also accepts a quoted decimal string — the encoding the precision contract above tells clients to use for sub-cent values, which the server's Pydantic coerces to an exact Decimal.

Responses always carry amount as a JSON number; use MonetaryAmount for those.

_id
string or null

Omitted means create; the server assigns a prc_… id. When present it must name a row already on that product, otherwise the request is a 422 (product.price_id_unknown, details.line_index naming the row). Ids are the server's; a client never chooses one.

_class
string or null
Enum: "price" null

Accepted on input but ignored — the server always assigns "price".

amount_is_gross
boolean or null

Whether amount includes VAT. Omitted, the tenant default.

vat_category
string or null
Enum: "S" "Z" "E" null
vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null
country_codes
Array of strings[ items = 2 characters ]
Reference (object) or null
valid_from
string or null <date>
valid_to
string or null <date>
is_campaign
boolean
Default: false
MonetaryAmountInput (object) or null
number or string
Default: 1
unit_of_measure
string
Default: "EA"
compute
object or null
priority
integer
Default: 0

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
required
object

self is the row's own resource URL, under the product that owns it. It survives an edit: a price id is the server's and is kept when a caller round-trips it.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

amount_is_gross
required
boolean

Whether amount includes VAT.

vat_category
required
string or null
Enum: "S" "Z" "E" null

VAT category (UNCL 5305) override for this row. Null inherits the Product-level vat_category and vat_rate_class. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "price",
  • "amount": {
    },
  • "amount_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "_links": {
    },
  • "amount": {
    },
  • "amount_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Partially update one price row

Body is an arbitrary subset of ProductPrice fields. The service merges the patch into the existing row, re-validates the result as a ProductPriceInput, and re-runs the prices-array validators (scoping guard, currency consistency, scoping-tuple uniqueness). A body _id that disagrees with the URL is a 422.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6
Request Body schema: application/json
required
property name*
additional property
any

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
required
object

self is the row's own resource URL, under the product that owns it. It survives an edit: a price id is the server's and is kept when a caller round-trips it.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

amount_is_gross
required
boolean

Whether amount includes VAT.

vat_category
required
string or null
Enum: "S" "Z" "E" null

VAT category (UNCL 5305) override for this row. Null inherits the Product-level vat_category and vat_rate_class. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "_links": {
    },
  • "amount": {
    },
  • "amount_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Remove one price row from a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Stock

List stock locations for the authenticated tenant

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (StockLocationResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a stock location

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 140 ] characters
location_type
string
Default: "warehouse"
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
description
string or null
is_default
boolean
Default: false

Mark this location as the tenant default. At most one location per tenant is the default; setting it here clears the flag on any previous default. The tenant's first location is made the default automatically.

is_active
boolean
Default: true

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

name
required
string
location_type
required
string
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
is_default
required
boolean
is_active
required
boolean
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
description
string or null

Request samples

Content type
application/json
{
  • "name": "Shop",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": false,
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "_id": "stl_a1b2c3d4e5f6",
  • "_class": "stock_location",
  • "_name": "Acme Corp",
  • "name": "string",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": true,
  • "is_active": true,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a stock location

Authorizations:
BearerAuth
path Parameters
stock_location_id
required
string
Example: stl_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

name
required
string
location_type
required
string
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
is_default
required
boolean
is_active
required
boolean
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
description
string or null

Response samples

Content type
application/json
{
  • "_id": "stl_a1b2c3d4e5f6",
  • "_class": "stock_location",
  • "_name": "Acme Corp",
  • "name": "string",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": true,
  • "is_active": true,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update a stock location (alias of PATCH — only supplied fields change)

Authorizations:
BearerAuth
path Parameters
stock_location_id
required
string
Example: stl_a1b2c3d4e5f6
Request Body schema: application/json
required
name
string [ 1 .. 140 ] characters
location_type
string
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
description
string or null
is_default
boolean
is_active
boolean

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

name
required
string
location_type
required
string
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
is_default
required
boolean
is_active
required
boolean
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
description
string or null

Request samples

Content type
application/json
{
  • "name": "string",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": true,
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "_id": "stl_a1b2c3d4e5f6",
  • "_class": "stock_location",
  • "_name": "Acme Corp",
  • "name": "string",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": true,
  • "is_active": true,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Partially update a stock location

Authorizations:
BearerAuth
path Parameters
stock_location_id
required
string
Example: stl_a1b2c3d4e5f6
Request Body schema: application/json
required
name
string [ 1 .. 140 ] characters
location_type
string
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
description
string or null
is_default
boolean
is_active
boolean

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

name
required
string
location_type
required
string
Enum: "shop" "store_room" "vehicle" "warehouse" "other"
is_default
required
boolean
is_active
required
boolean
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
description
string or null

Request samples

Content type
application/json
{
  • "name": "string",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": true,
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "_id": "stl_a1b2c3d4e5f6",
  • "_class": "stock_location",
  • "_name": "Acme Corp",
  • "name": "string",
  • "location_type": "shop",
  • "description": "string",
  • "is_default": true,
  • "is_active": true,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a stock location

Rejected with 409 when the location is the tenant default (reassign first) or still holds stock.

Authorizations:
BearerAuth
path Parameters
stock_location_id
required
string
Example: stl_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List the movement ledger for one product at one location

Authorizations:
BearerAuth
query Parameters
product_id
required
string
stock_location_id
required
string
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (StockMovementResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Record a stock movement (opening / receipt / issue / adjustment)

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

movement_type
required
string
Enum: "opening" "receipt" "issue" "adjustment"

opening/receipt add stock (positive quantity_delta, unit_cost required); issue removes stock (negative); adjustment is a signed correction. count and transfer have their own endpoints.

quantity_delta
required
number

Signed quantity change; must be non-zero.

MonetaryAmountInput (object) or null

Required on opening/receipt so weighted-average cost recomputes.

reason
string or null
dedupe_key
string or null [ 1 .. 128 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The existing movement is returned unchanged.

effective_at
integer or null

Business date (unix seconds); defaults to now.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The movement type and its signed quantity, e.g. "receipt +20".

movement_type
required
string
Enum: "opening" "receipt" "issue" "transfer" "adjustment" "count"
quantity_delta
required
number
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

dedupe_key
required
string or null
effective_at
required
integer
required
Reference (object) or null

The offer or invoice this movement fulfils (a dispatch line).

document_line_item_id
required
string or null
required
Reference (object) or null

The receipt, stocktake or dispatch that posted this movement.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

Reference (object) or null
MonetaryAmount (object) or null
balance_after
number or null
reason
string or null

Request samples

Content type
application/json
{
  • "product": {
    },
  • "stock_location": {
    },
  • "movement_type": "opening",
  • "quantity_delta": 0,
  • "unit_cost": {
    },
  • "reason": "string",
  • "dedupe_key": "string",
  • "effective_at": 0
}

Response samples

Content type
application/json
{
  • "_id": "stm_a1b2c3d4e5f6",
  • "_class": "stock_movement",
  • "_name": "string",
  • "tenant": {
    },
  • "product": {
    },
  • "stock_location": {
    },
  • "counterparty_location": {
    },
  • "movement_type": "opening",
  • "quantity_delta": 0,
  • "unit_cost": {
    },
  • "value_delta": {
    },
  • "average_cost_after": {
    },
  • "balance_after": 0,
  • "reason": "string",
  • "dedupe_key": "string",
  • "effective_at": 0,
  • "source_document": {
    },
  • "document_line_item_id": "string",
  • "stock_document": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Post a physical-count variance

Supply the absolute counted quantity; the service posts a count movement for the difference from the current on-hand.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

counted_quantity
required
number >= 0

Absolute counted quantity; the service posts the variance.

reason
string or null
dedupe_key
string or null [ 1 .. 128 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The existing movement is returned unchanged.

effective_at
integer or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The movement type and its signed quantity, e.g. "receipt +20".

movement_type
required
string
Enum: "opening" "receipt" "issue" "transfer" "adjustment" "count"
quantity_delta
required
number
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

dedupe_key
required
string or null
effective_at
required
integer
required
Reference (object) or null

The offer or invoice this movement fulfils (a dispatch line).

document_line_item_id
required
string or null
required
Reference (object) or null

The receipt, stocktake or dispatch that posted this movement.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

Reference (object) or null
MonetaryAmount (object) or null
balance_after
number or null
reason
string or null

Request samples

Content type
application/json
{
  • "product": {
    },
  • "stock_location": {
    },
  • "counted_quantity": 0,
  • "reason": "string",
  • "dedupe_key": "string",
  • "effective_at": 0
}

Response samples

Content type
application/json
{
  • "_id": "stm_a1b2c3d4e5f6",
  • "_class": "stock_movement",
  • "_name": "string",
  • "tenant": {
    },
  • "product": {
    },
  • "stock_location": {
    },
  • "counterparty_location": {
    },
  • "movement_type": "opening",
  • "quantity_delta": 0,
  • "unit_cost": {
    },
  • "value_delta": {
    },
  • "average_cost_after": {
    },
  • "balance_after": 0,
  • "reason": "string",
  • "dedupe_key": "string",
  • "effective_at": 0,
  • "source_document": {
    },
  • "document_line_item_id": "string",
  • "stock_document": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Transfer stock between two locations

Emits an issue on the source and a receipt on the destination in one transaction, carrying the source's average cost across.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

quantity
required
number > 0
reason
string or null
dedupe_key
string or null [ 1 .. 128 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The existing movement is returned unchanged.

effective_at
integer or null

Responses

Response Schema: application/json
required
object (StockMovementResponse)
required
object (StockMovementResponse)

Request samples

Content type
application/json
{
  • "product": {
    },
  • "from_location": {
    },
  • "to_location": {
    },
  • "quantity": 0,
  • "reason": "string",
  • "dedupe_key": "string",
  • "effective_at": 0
}

Response samples

Content type
application/json
{
  • "source": {
    },
  • "destination": {
    }
}

Stock-development series (running on-hand balance over time)

Authorizations:
BearerAuth
query Parameters
product_id
required
string
stock_location_id
string

Omit to get the product's total on-hand across all locations; supply to scope the series to one location.

Responses

Response Schema: application/json
required
Array of objects

Response samples

Content type
application/json
{
  • "series": [
    ]
}

List stock levels for a product (optionally one location)

Authorizations:
BearerAuth
query Parameters
product_id
required
string
stock_location_id
string

Responses

Response Schema: application/json
required
Array of objects (StockLevelResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Set or clear the reorder point on a level

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

reorder_point
number or null >= 0

Responses

Response Schema: application/json
_id
required
string

Composite id "{product_id}.{stock_location_id}".

_class
required
string
on_hand
required
number
reserved
required
number
available
required
number

Computed on-hand minus reserved (never stored).

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
object

Backend-computed on_hand x average_cost.

stocking_unit_of_measure
required
string
last_counted_at
required
integer or null

The business date of the last stocktake that counted this level.

required
Reference (object) or null

The stocktake that last counted this level.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

reorder_point
number or null

Request samples

Content type
application/json
{
  • "product": {
    },
  • "stock_location": {
    },
  • "reorder_point": 0
}

Response samples

Content type
application/json
{
  • "_id": "prd_abc.stl_xyz",
  • "_class": "stock_level",
  • "tenant": {
    },
  • "product": {
    },
  • "stock_location": {
    },
  • "on_hand": 0,
  • "reserved": 0,
  • "available": 0,
  • "average_cost": {
    },
  • "stock_value": {
    },
  • "reorder_point": 0,
  • "stocking_unit_of_measure": "string",
  • "last_counted_at": 0,
  • "last_count": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

List goods receipts, newest first

Authorizations:
BearerAuth
query Parameters
stock_location_id
string
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (StockReceiptResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Post a goods receipt — one receipt movement per line, then the applied record

Lines post first, keyed {dedupe_key}:{line dedupe_key} so a retried sheet replays already-posted lines as no-ops; the header is written once every line landed. When a line fails the response is a 422 whose details.lines carries every line's outcome and no header is written.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

dedupe_key
required
string [ 1 .. 64 ] characters

Required. A second write with the same key within the tenant does not create a second row. The existing sheet is returned unchanged, every line replayed.

required
Array of objects (StockReceiptLineCreate) [ 1 .. 500 ] items
effective_at
integer or null

Business date (unix seconds); defaults to now.

reference
string or null

The supplier's delivery-note number, as given.

note
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

effective_at
required
integer
reference
required
string or null
note
required
string or null
dedupe_key
required
string
required
Array of objects (StockReceiptLine)
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
Array of objects (StockReceiptLineResult)

The outcome per line of this post.

Request samples

Content type
application/json
{
  • "stock_location": {
    },
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "effective_at": 0,
  • "reference": "string",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "_id": "srct_a1b2c3d4e5f6",
  • "_class": "stock_receipt",
  • "_name": "string",
  • "tenant": {
    },
  • "stock_location": {
    },
  • "effective_at": 0,
  • "reference": "string",
  • "note": "string",
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "lines_result": [
    ]
}

Get a goods receipt

Authorizations:
BearerAuth
path Parameters
stock_receipt_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

effective_at
required
integer
reference
required
string or null
note
required
string or null
dedupe_key
required
string
required
Array of objects (StockReceiptLine)
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null

Response samples

Content type
application/json
{
  • "_id": "srct_a1b2c3d4e5f6",
  • "_class": "stock_receipt",
  • "_name": "string",
  • "tenant": {
    },
  • "stock_location": {
    },
  • "effective_at": 0,
  • "reference": "string",
  • "note": "string",
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

List stocktakes, newest first

Authorizations:
BearerAuth
query Parameters
stock_location_id
string
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (StockCountResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Post a stocktake — a count movement per line with a variance, then the applied sheet

Every line's variance is measured against the ledger balance as of the count date, so a backdated count does not undo movements posted since. Lines whose counted figure matches post no movement but stay on the sheet. Lines post first, keyed {dedupe_key}:{line dedupe_key}, so a retried sheet replays; the sheet is written once every line landed, and every counted level is stamped last_counted_at.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

dedupe_key
required
string [ 1 .. 64 ] characters

Required. A second write with the same key within the tenant does not create a second row. The existing sheet is returned unchanged, every line replayed.

required
Array of objects (StockCountLineCreate) [ 1 .. 500 ] items
effective_at
integer or null

The count date (unix seconds); defaults to now. Variances are measured against the ledger as of this date.

note
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

effective_at
required
integer
note
required
string or null
dedupe_key
required
string
required
Array of objects (StockCountLine)
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
Array of objects (StockCountLineResult)

Request samples

Content type
application/json
{
  • "stock_location": {
    },
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "effective_at": 0,
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "_id": "stc_a1b2c3d4e5f6",
  • "_class": "stock_count",
  • "_name": "string",
  • "tenant": {
    },
  • "stock_location": {
    },
  • "effective_at": 0,
  • "note": "string",
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "lines_result": [
    ]
}

Get a stocktake

Authorizations:
BearerAuth
path Parameters
stock_count_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

effective_at
required
integer
note
required
string or null
dedupe_key
required
string
required
Array of objects (StockCountLine)
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null

Response samples

Content type
application/json
{
  • "_id": "stc_a1b2c3d4e5f6",
  • "_class": "stock_count",
  • "_name": "string",
  • "tenant": {
    },
  • "stock_location": {
    },
  • "effective_at": 0,
  • "note": "string",
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

List goods dispatches, newest first

Authorizations:
BearerAuth
query Parameters
document_id
string

Only dispatches shipped against this offer or invoice; the response then also carries shipped_by_line.

limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (StockDispatchResponse)
next_token
required
string or null
object

Present when filtered by document_id — quantity already shipped per document line, across every dispatch.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string",
  • "shipped_by_line": {
    }
}

Ship goods — an issue movement per tracked line, then the numbered dispatch record

From an accepted offer or an invoice (any status but cancelled), or on its own. Every tracked line posts an issue movement keyed {dedupe_key}:{line dedupe_key} naming the customer document and the dispatch; a draft invoice's reservation is lowered in the same write. Untracked lines are skipped and reported. The header is written once every line landed and numbered on the tenant's delivery-note series.

Authorizations:
BearerAuth
Request Body schema: application/json
required
dedupe_key
required
string [ 1 .. 64 ] characters

Required. A second write with the same key within the tenant does not create a second row. The existing sheet is returned unchanged, every line replayed.

required
Array of objects (StockDispatchLineCreate) [ 1 .. 500 ] items
Reference (object) or null

The accepted offer or the invoice being shipped. Omit for a standalone dispatch.

Reference (object) or null

Recipient of a standalone dispatch.

Reference (object) or null

The location the goods leave from; defaults to the tenant default.

effective_at
integer or null
reference
string or null

A customer order or waybill number.

note
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The dispatch number once posted.

dispatch_number
required
string
status
required
string
Enum: "draft" "posted"
required
Reference (object) or null
required
Reference (object) or null
recipient_name
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

effective_at
required
integer
reference
required
string or null
note
required
string or null
dedupe_key
required
string
required
Array of objects (StockDispatchLine)
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
Array of objects (StockDispatchLineResult)

Request samples

Content type
application/json
{
  • "source_document": {
    },
  • "business_partner": {
    },
  • "stock_location": {
    },
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "effective_at": 0,
  • "reference": "string",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "_id": "sdp_a1b2c3d4e5f6",
  • "_class": "stock_dispatch",
  • "_name": "string",
  • "dispatch_number": "string",
  • "status": "draft",
  • "source_document": {
    },
  • "business_partner": {
    },
  • "recipient_name": "string",
  • "tenant": {
    },
  • "stock_location": {
    },
  • "effective_at": 0,
  • "reference": "string",
  • "note": "string",
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "lines_result": [
    ]
}

Get a goods dispatch

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The dispatch number once posted.

dispatch_number
required
string
status
required
string
Enum: "draft" "posted"
required
Reference (object) or null
required
Reference (object) or null
recipient_name
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

effective_at
required
integer
reference
required
string or null
note
required
string or null
dedupe_key
required
string
required
Array of objects (StockDispatchLine)
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null

Response samples

Content type
application/json
{
  • "_id": "sdp_a1b2c3d4e5f6",
  • "_class": "stock_dispatch",
  • "_name": "string",
  • "dispatch_number": "string",
  • "status": "draft",
  • "source_document": {
    },
  • "business_partner": {
    },
  • "recipient_name": "string",
  • "tenant": {
    },
  • "stock_location": {
    },
  • "effective_at": 0,
  • "reference": "string",
  • "note": "string",
  • "dedupe_key": "string",
  • "lines": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

List a dispatch's generated documents

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string
Example: sdp_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (StockDispatchDocumentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Request the delivery note PDF

Writes the document in pdf_pending and publishes the event the generator subscribes to. The dispatch must be posted; a posted dispatch already has one requested for it.

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string
Example: sdp_a1b2c3d4e5f6
Request Body schema: application/json
optional
document_type
string (StockDispatchDocumentType)
Value: "delivery_note"

One artefact today, the rendered delivery note.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
stock_dispatch_id
required
string
document_type
required
string (StockDispatchDocumentType)
Value: "delivery_note"

One artefact today, the rendered delivery note.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF; null until the worker attaches it.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "document_type": "delivery_note"
}

Response samples

Content type
application/json
{
  • "_id": "sddoc_a1b2c3d4e5f6789012345",
  • "_class": "stock_dispatch_document",
  • "stock_dispatch_id": "sdp_a1b2c3d4e5f6",
  • "document_type": "delivery_note",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Get one of a dispatch's documents

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string
Example: sdp_a1b2c3d4e5f6
stock_dispatch_document_id
required
string
Example: sddoc_a1b2c3d4e5f6789012345

Responses

Response Schema: application/json
_id
required
string
_class
required
string
stock_dispatch_id
required
string
document_type
required
string (StockDispatchDocumentType)
Value: "delivery_note"

One artefact today, the rendered delivery note.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF; null until the worker attaches it.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "sddoc_a1b2c3d4e5f6789012345",
  • "_class": "stock_dispatch_document",
  • "stock_dispatch_id": "sdp_a1b2c3d4e5f6",
  • "document_type": "delivery_note",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Attach the rendered PDF, or retry a failed render

Setting file on a pdf_pending document moves it to pdf_ready. Idempotent: replaying on an already-attached document returns the PDF it already has. Setting status to pdf_pending re-requests the render of a failed document.

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string
Example: sdp_a1b2c3d4e5f6
stock_dispatch_document_id
required
string
Example: sddoc_a1b2c3d4e5f6789012345
Request Body schema: application/json
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
string
Value: "pdf_pending"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
stock_dispatch_id
required
string
document_type
required
string (StockDispatchDocumentType)
Value: "delivery_note"

One artefact today, the rendered delivery note.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF; null until the worker attaches it.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "file": {
    },
  • "status": "pdf_pending"
}

Response samples

Content type
application/json
{
  • "_id": "sddoc_a1b2c3d4e5f6789012345",
  • "_class": "stock_dispatch_document",
  • "stock_dispatch_id": "sdp_a1b2c3d4e5f6",
  • "document_type": "delivery_note",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Attach the rendered PDF, or retry a failed render

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string
Example: sdp_a1b2c3d4e5f6
stock_dispatch_document_id
required
string
Example: sddoc_a1b2c3d4e5f6789012345
Request Body schema: application/json
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
string
Value: "pdf_pending"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
stock_dispatch_id
required
string
document_type
required
string (StockDispatchDocumentType)
Value: "delivery_note"

One artefact today, the rendered delivery note.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF; null until the worker attaches it.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "file": {
    },
  • "status": "pdf_pending"
}

Response samples

Content type
application/json
{
  • "_id": "sddoc_a1b2c3d4e5f6789012345",
  • "_class": "stock_dispatch_document",
  • "stock_dispatch_id": "sdp_a1b2c3d4e5f6",
  • "document_type": "delivery_note",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Delete a document and soft-delete its PDF

Authorizations:
BearerAuth
path Parameters
stock_dispatch_id
required
string
Example: sdp_a1b2c3d4e5f6
stock_dispatch_document_id
required
string
Example: sddoc_a1b2c3d4e5f6789012345

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List posted stock documents — receipts, stocktakes and dispatches — newest first

One timeline across the three applied stock documents. Capped at 200 rows; truncated says when the filters should narrow. counts gives the rows per kind after the location, date and search filters so a kind filter chip can show its count.

Authorizations:
BearerAuth
query Parameters
kind
string (StockDocumentKind)
Enum: "stock_receipt" "stock_count" "stock_dispatch"
stock_location_id
string
from
string <date>

ISO date, inclusive, on effective_at.

to
string <date>

ISO date, inclusive, on effective_at.

q
string

Matches the dispatch number, the receipt reference, the recipient and the customer document number.

Responses

Response Schema: application/json
required
Array of objects (StockDocumentRow)
required
object (StockDocumentCounts)

Rows per kind after the location, date and search filters, before the kind filter.

truncated
required
boolean

More than 200 rows matched; narrow the filters.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "counts": {
    },
  • "truncated": true
}

The stock overview — every product x location, low rows first, with header totals

Sorted for the overview page: negative available first, then rows at or below their reorder point by shortfall, then the rest by product and location name. Capped at 2,000 rows (stats.truncated) — narrow by location past that. committed is what accepted offers still claim per product, attributed to the level at the default location.

Authorizations:
BearerAuth
query Parameters
stock_location_id
string
low_only
boolean

Responses

Response Schema: application/json
required
Array of objects (StockSummaryRow)
required
object (StockSummaryStats)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "stats": {
    }
}

Inventory valuation with a total

Authorizations:
BearerAuth

Responses

Response Schema: application/json
Array of objects (StockLevelResponse)
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total_value": {
    }
}

Levels whose available quantity is at or below their reorder point, largest shortfall first

Authorizations:
BearerAuth
query Parameters
stock_location_id
string

Responses

Response Schema: application/json
Array of objects (StockLevelResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

The tenant-wide movement ledger, newest first

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (StockMovementResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Invoices

List the attempts to collect this invoice from the buyer's phone

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string

Responses

Response Schema: application/json
required
Array of objects (PaymentCollection)
total
required
integer
page
required
integer
page_size
required
integer

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "page_size": 0
}

Ask this invoice's buyer to pay it from their phone

Starts a collection on one of the tenant's rails and returns whatever the buyer needs in order to pay. The money settles into the tenant's own merchant account — Raccoon never holds it — and is booked against this invoice as an ordinary payment when the rail confirms.

Rejected with 422 when the rail is switched off, not offered in the tenant's country, or has no credentials yet.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Request Body schema: application/json
required
rail_id
required
string
object (MonetaryAmount)

Optional — defaults to the invoice's open balance. Must be in the invoice's own currency, which makes a mismatch structurally unreachable rather than a 422 the buyer meets holding their phone.

phone_number
string <= 20 characters

Where to push the request, for a rail that asks a phone rather than showing a code — required for such a rail, ignored by the rest. A Kenyan number is accepted in any form a tenant types it (0712…, +254 712…, 254712…) and normalised before it reaches the provider.

dedupe_key
string [ 1 .. 64 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The collection already started is returned unchanged; the rail is asked once.

stub_behaviour
string
Enum: "succeed" "pending" "fail"

Drives the stub adapter through a state a real rail would take minutes to reach. Ignored once a rail has a real adapter.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

rail_id
required
string
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

reference
required
string

What the buyer's payment will actually carry back, and — on a rail that cannot confirm itself — the only thing tying the money to this invoice when it lands. A rail that mints a structured reference (an ISO 11649 RF…, a Swiss QRR) reports that here rather than the invoice number it was derived from, because the invoice number never appears on the transfer.

status
required
string
Enum: "pending" "succeeded" "failed" "expired" "cancelled"

pending is the honest resting state of every rail that confirms later; a collection reaches succeeded only once money is actually booked.

required
object

What the buyer needs in order to pay — payload carries the rail's own artefact (a QR string, a link), and the rest is what the screen shows beside it. The keys are labels the screen translates (payee, iban, reference, reference_type, amount, phone_number, rail), except confirmation and note, whose values are codes the screen words in the reader's language: confirmation is matched_by_reference, sent_to_phone or settles_on_paypal_confirmation, note is demonstration_only.

provider_reference
required
string or null

The rail's own receipt, once it has one.

stub_behaviour
required
string or null
expires_at
required
integer or null
settled_at
required
integer or null
failure_reason
required
string or null
required
Reference (object) or null

The payment this collection booked, once it settled.

dedupe_key
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Request samples

Content type
application/json
{
  • "rail_id": "girocode",
  • "amount": {
    },
  • "phone_number": "0712345678",
  • "dedupe_key": "string",
  • "stub_behaviour": "succeed"
}

Response samples

Content type
application/json
{
  • "_id": "pcl_9f2c1a4b7e05",
  • "_class": "string",
  • "invoice": {
    },
  • "rail_id": "mpesa_push",
  • "amount": {
    },
  • "reference": "string",
  • "status": "pending",
  • "instruction": {
    },
  • "provider_reference": "string",
  • "stub_behaviour": "string",
  • "expires_at": 0,
  • "settled_at": 0,
  • "failure_reason": "string",
  • "payment": {
    },
  • "dedupe_key": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Read one collection

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
collection_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

rail_id
required
string
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

reference
required
string

What the buyer's payment will actually carry back, and — on a rail that cannot confirm itself — the only thing tying the money to this invoice when it lands. A rail that mints a structured reference (an ISO 11649 RF…, a Swiss QRR) reports that here rather than the invoice number it was derived from, because the invoice number never appears on the transfer.

status
required
string
Enum: "pending" "succeeded" "failed" "expired" "cancelled"

pending is the honest resting state of every rail that confirms later; a collection reaches succeeded only once money is actually booked.

required
object

What the buyer needs in order to pay — payload carries the rail's own artefact (a QR string, a link), and the rest is what the screen shows beside it. The keys are labels the screen translates (payee, iban, reference, reference_type, amount, phone_number, rail), except confirmation and note, whose values are codes the screen words in the reader's language: confirmation is matched_by_reference, sent_to_phone or settles_on_paypal_confirmation, note is demonstration_only.

provider_reference
required
string or null

The rail's own receipt, once it has one.

stub_behaviour
required
string or null
expires_at
required
integer or null
settled_at
required
integer or null
failure_reason
required
string or null
required
Reference (object) or null

The payment this collection booked, once it settled.

dedupe_key
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Response samples

Content type
application/json
{
  • "_id": "pcl_9f2c1a4b7e05",
  • "_class": "string",
  • "invoice": {
    },
  • "rail_id": "mpesa_push",
  • "amount": {
    },
  • "reference": "string",
  • "status": "pending",
  • "instruction": {
    },
  • "provider_reference": "string",
  • "stub_behaviour": "string",
  • "expires_at": 0,
  • "settled_at": 0,
  • "failure_reason": "string",
  • "payment": {
    },
  • "dedupe_key": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Give up on a collection

The buyer walked away, or chose another rail. A settled collection cannot be cancelled — the money is already booked.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
collection_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

rail_id
required
string
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

reference
required
string

What the buyer's payment will actually carry back, and — on a rail that cannot confirm itself — the only thing tying the money to this invoice when it lands. A rail that mints a structured reference (an ISO 11649 RF…, a Swiss QRR) reports that here rather than the invoice number it was derived from, because the invoice number never appears on the transfer.

status
required
string
Enum: "pending" "succeeded" "failed" "expired" "cancelled"

pending is the honest resting state of every rail that confirms later; a collection reaches succeeded only once money is actually booked.

required
object

What the buyer needs in order to pay — payload carries the rail's own artefact (a QR string, a link), and the rest is what the screen shows beside it. The keys are labels the screen translates (payee, iban, reference, reference_type, amount, phone_number, rail), except confirmation and note, whose values are codes the screen words in the reader's language: confirmation is matched_by_reference, sent_to_phone or settles_on_paypal_confirmation, note is demonstration_only.

provider_reference
required
string or null

The rail's own receipt, once it has one.

stub_behaviour
required
string or null
expires_at
required
integer or null
settled_at
required
integer or null
failure_reason
required
string or null
required
Reference (object) or null

The payment this collection booked, once it settled.

dedupe_key
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Response samples

Content type
application/json
{
  • "_id": "pcl_9f2c1a4b7e05",
  • "_class": "string",
  • "invoice": {
    },
  • "rail_id": "mpesa_push",
  • "amount": {
    },
  • "reference": "string",
  • "status": "pending",
  • "instruction": {
    },
  • "provider_reference": "string",
  • "stub_behaviour": "string",
  • "expires_at": 0,
  • "settled_at": 0,
  • "failure_reason": "string",
  • "payment": {
    },
  • "dedupe_key": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Report that a collection was paid (service-to-service)

Books the money through the ordinary allocation path, so the invoice gets a payment exactly as if a human had recorded it.

Gated to service identities and superusers only — deliberately stricter than its sibling routes, because a forged settlement is money rather than provenance. Repeated delivery is expected on every rail researched and books once.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
collection_id
required
string
Request Body schema: application/json
required
provider_reference
required
string

The rail's own receipt (an M-Pesa code, a Pix txid).

object (MonetaryAmount)

Optional — defaults to what the collection asked for.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

rail_id
required
string
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

reference
required
string

What the buyer's payment will actually carry back, and — on a rail that cannot confirm itself — the only thing tying the money to this invoice when it lands. A rail that mints a structured reference (an ISO 11649 RF…, a Swiss QRR) reports that here rather than the invoice number it was derived from, because the invoice number never appears on the transfer.

status
required
string
Enum: "pending" "succeeded" "failed" "expired" "cancelled"

pending is the honest resting state of every rail that confirms later; a collection reaches succeeded only once money is actually booked.

required
object

What the buyer needs in order to pay — payload carries the rail's own artefact (a QR string, a link), and the rest is what the screen shows beside it. The keys are labels the screen translates (payee, iban, reference, reference_type, amount, phone_number, rail), except confirmation and note, whose values are codes the screen words in the reader's language: confirmation is matched_by_reference, sent_to_phone or settles_on_paypal_confirmation, note is demonstration_only.

provider_reference
required
string or null

The rail's own receipt, once it has one.

stub_behaviour
required
string or null
expires_at
required
integer or null
settled_at
required
integer or null
failure_reason
required
string or null
required
Reference (object) or null

The payment this collection booked, once it settled.

dedupe_key
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Request samples

Content type
application/json
{
  • "provider_reference": "string",
  • "amount": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "pcl_9f2c1a4b7e05",
  • "_class": "string",
  • "invoice": {
    },
  • "rail_id": "mpesa_push",
  • "amount": {
    },
  • "reference": "string",
  • "status": "pending",
  • "instruction": {
    },
  • "provider_reference": "string",
  • "stub_behaviour": "string",
  • "expires_at": 0,
  • "settled_at": 0,
  • "failure_reason": "string",
  • "payment": {
    },
  • "dedupe_key": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Report what the buyer must do to pay (service-to-service)

Completes the instruction on a collection whose rail had to ask a provider for it. A rail whose adapter runs in process fills this in before the start request returns and is refused here; a remote one leaves the collection at state: requesting until its worker reports back through this route.

Send failure_reason instead of a payload when the provider refused the request, so the collection closes rather than waiting for a code that is never coming. One of the two is required: a body carrying neither is a 422, because it would leave the collection waiting with an empty artefact and no reason given.

Gated to service identities and superusers only, for the same reason as its sibling: this writes what a buyer is shown, so a forged instruction is a code pointing at somebody else's account.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
collection_id
required
string
Request Body schema: application/json
required
payload
string <= 4096 characters

The rail's own artefact — for PayPal, the approval link the QR encodes.

object

What the screen shows beside the code. confirmation and note carry one of the listed codes, never prose; any other value is a 422.

expires_in_seconds
integer or null [ 1 .. 86400 ]

How long the artefact is good for, when the provider says.

failure_reason
string or null <= 500 characters

Sent instead of a payload when the provider refused. Closes the collection rather than leaving it waiting for a code.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

rail_id
required
string
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

reference
required
string

What the buyer's payment will actually carry back, and — on a rail that cannot confirm itself — the only thing tying the money to this invoice when it lands. A rail that mints a structured reference (an ISO 11649 RF…, a Swiss QRR) reports that here rather than the invoice number it was derived from, because the invoice number never appears on the transfer.

status
required
string
Enum: "pending" "succeeded" "failed" "expired" "cancelled"

pending is the honest resting state of every rail that confirms later; a collection reaches succeeded only once money is actually booked.

required
object

What the buyer needs in order to pay — payload carries the rail's own artefact (a QR string, a link), and the rest is what the screen shows beside it. The keys are labels the screen translates (payee, iban, reference, reference_type, amount, phone_number, rail), except confirmation and note, whose values are codes the screen words in the reader's language: confirmation is matched_by_reference, sent_to_phone or settles_on_paypal_confirmation, note is demonstration_only.

provider_reference
required
string or null

The rail's own receipt, once it has one.

stub_behaviour
required
string or null
expires_at
required
integer or null
settled_at
required
integer or null
failure_reason
required
string or null
required
Reference (object) or null

The payment this collection booked, once it settled.

dedupe_key
required
string or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Request samples

Content type
application/json
{
  • "payload": "string",
  • "display": {
    },
  • "expires_in_seconds": 1,
  • "failure_reason": "string"
}

Response samples

Content type
application/json
{
  • "_id": "pcl_9f2c1a4b7e05",
  • "_class": "string",
  • "invoice": {
    },
  • "rail_id": "mpesa_push",
  • "amount": {
    },
  • "reference": "string",
  • "status": "pending",
  • "instruction": {
    },
  • "provider_reference": "string",
  • "stub_behaviour": "string",
  • "expires_at": 0,
  • "settled_at": 0,
  • "failure_reason": "string",
  • "payment": {
    },
  • "dedupe_key": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

List invoices (newest first)

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

status
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
payment_status
string
Enum: "unpaid" "partially_paid" "paid"

Filter on the settlement axis. Independent of status: an invoice can be overdue and partially_paid at the same time. An unrecognised value is rejected with 422 rather than matching nothing.

business_partner_id
string
type_id
string
offer_id
string

Only the invoices raised from this offer. One offer can produce several invoices, so this is how they are listed — the offer keeps no list of its own.

invoice_number
string

Only the invoice carrying this number, ignoring letter case and surrounding whitespace. Answered from a lookup row written when the number is stamped, not from the search index, and returned in one page with a null next_token. A draft has no number and never matches. With q, it narrows the search hits instead.

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (InvoiceResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a new invoice (starts as draft)

A credit note is created here too: document_type_code: "381" with preceding_invoice naming the issued invoice it credits. Send the parties, currency and lines. A line naming credited_line_item takes that line of the original with the quantity sent, and its stored figures; any other line is worked out as entered. The credit note takes the original's show_gross_values_per_line_item, and its figures are worked out again at finalize against the credit notes issued by then. Amounts stay positive; a line is taken back with a negative quantity, which only a credit note accepts.

Credit-note rejections (422), also on update and finalize: credit_note.preceding_invoice_required, credit_note.original_not_found, credit_note.original_ambiguous (two invoices carry the number; add its issue date), credit_note.original_not_issued (a draft or cancelled original), credit_note.original_is_credit_note, credit_note.currency_differs, credit_note.company_differs (a credit note is issued by the original's company), credit_note.total_negative, and credit_note.exceeds_original (more than the original's total less the issued credit notes already against it). A credited line is refused with credit_note.credited_line_not_found (no such line on the original), credit_note.credited_line_repeated (two lines credit one) or credit_note.credited_quantity_exceeds_line (a quantity not above 0 or above what is left of the line); on any other document with billing_document.credited_line_item_on_credit_note_only. A negative quantity is only for a line that credits no line of the original. A negative quantity on any other document is billing_document.line_quantity_negative.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

dedupe_key
string or null [ 1 .. 64 ] characters

Optional. A second create with the same key within the tenant does not create a second invoice. The invoice already created is returned unchanged; the repeated body is not compared with it, and only its shape is checked. A key already used for another kind of record is a 409.

Reference (object) or null

Issuing Company (EN 16931 BG-7 Seller). Auto-resolved from the tenant's invoice-company config when omitted on create. Per the no-bare-id rule (architecture.md#Embedded References) the wire shape is the full Reference object.

Reference (object) or null

Optional tenant-defined sales channel selected for this invoice. Snapshotted on the invoice.

issue_date
string or null <date>
due_date
string or null <date>
tax_point_date
string or null <date>

EN 16931 BT-7 — value-added-tax point date.

actual_delivery_date
string or null <date>

EN 16931 BT-72 — actual delivery date.

document_type_code
string or null
Enum: "380" "381" "384" "386" "326" null

EN 16931 BT-3 (UNCL 1001). 380=commercial invoice, 381=credit note, 384=corrected invoice, 386=prepayment invoice, 326=partial invoice. A credit note requires preceding_invoice.

currency
string or null = 3 characters
buyer_reference
string or null

EN 16931 BT-10. Often the buyer's PO number or Leitweg-ID. Left out, the business partner's Leitweg-ID is used, else its number for us (partner_assigned_number); sent empty or null, the document has none.

purchase_order_reference
string or null

EN 16931 BT-13. Left out, the business partner's purchase_order_reference is used; sent empty or null, the document has none.

contract_reference
string or null

EN 16931 BT-12.

project_reference
string or null

EN 16931 BT-11.

subject
string or null

What the invoice is about, printed as its subject line.

InvoicePeriod (object) or null
InvoiceBillingReference (object) or null

EN 16931 BG-3: the earlier invoice this one refers to, by its number and optionally its issue date. Required for a credit note (381), which may only credit an issued invoice of this tenant.

buyer_name
string or null

EN 16931 BT-44 — buyer name. Defaults to the partner's company/full name.

buyer_legal_registration_id
string or null

EN 16931 BT-47. Defaults to the partner's company_register identifier.

buyer_identifier
string or null

EN 16931 BT-46 — party identifier (GLN, DUNS, etc.). Defaults to the partner's GLN, together with buyer_identifier_scheme_id.

buyer_identifier_scheme_id
string or null

EN 16931 BT-46-1 — ISO/IEC 6523 scheme of buyer_identifier (0088 for a GLN). Taken with the identifier: when buyer_identifier is sent, this is what is sent beside it.

buyer_customer_number
string or null

The buyer's customer number with the seller (DIN 5008 Kundennummer). Defaults to the business partner's.

buyer_vat_id
string or null

EN 16931 BT-48.

buyer_vat_id_type
string or null

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb). Defaulted from the partner's VAT-class identifier when omitted.

InvoicePartyContact (object) or null
InvoiceElectronicAddress (object) or null

EN 16931 BT-49. Left out, the partner's Peppol ID is used (split into scheme and value), else its Leitweg-ID under scheme 0204; sent null, the document has none.

InvoicePayee (object) or null
payment_means_code
string or null

EN 16931 BT-81 (UNCL 4461). Defaults from tenant config.

payment_terms_text
string or null

EN 16931 BT-20.

InvoicePaymentTerms (object) or null

Structured skonto / late-payment block. Additive to BT-20 payment_terms_text — both render when supplied.

remittance_information
string or null

EN 16931 BT-83 — payment reference / Verwendungszweck.

Array of objects (InvoiceLineItemCreate)
notes
Array of strings
Default: []

EN 16931 BT-22 — invoice notes (0..n). Each entry is rendered as its own paragraph below the totals. The author handles translation; the renderer prints what is supplied.

show_gross_values_per_line_item
boolean

Whether each line shows its value with VAT included (true) or net of VAT (false). Omitted on create, the invoice takes the default_show_gross_values_per_line_item of its invoice type. Draft only; changing it recalculates the lines from their prices as entered and never changes a price. A credit note always takes the value of the invoice it credits.

prepaid_amount
number >= 0

EN 16931 BT-113: an amount already paid, in the invoice's currency, taken off the amount payable. Draft only. Defaults to 0. More than tax_inclusive + rounding_amount is a 422.

type_id
string [ 1 .. 100 ] characters

The invoice-class tenant type this invoice is created under. Every invoice has one. It decides the letterhead, the numbering and the payment defaults. Omitted, the invoice is created under the tenant's default invoice type; that is a 422 when the tenant has several and marks none of them default.

schema_version
string or null
object
Default: {}
object

Optional. When omitted, the server snapshots the partner's preferred addresses for each slot declared by the invoice type. When supplied, the slot keys must be a subset of the invoice type's address_slots.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "dedupe_key": "string",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "tax_point_date": "2019-08-24",
  • "actual_delivery_date": "2019-08-24",
  • "document_type_code": "380",
  • "currency": "EUR",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "subject": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_identifier_scheme_id": "string",
  • "buyer_customer_number": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_means_code": "string",
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [ ],
  • "show_gross_values_per_line_item": true,
  • "prepaid_amount": 0,
  • "type_id": "standard_invoice",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    }
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Get invoice by ID

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Update invoice fields and/or status

{"status": "finalized"} issues the invoice: it refreshes the seller snapshot, re-rates VAT at the time of supply, stamps the number from the tenant's numbering schema in the same atomic write, and hands the PDF off to the document generator. A finalize carries no other field changes — save the edits first — and only a draft can be finalized. An invoice with an intra-Community supply of goods (VAT category K) is refused with 422 until it has an actual_delivery_date or an invoicing_period, and a shipping address with its country (EN 16931 BR-IC-11/12).

A credit note is numbered in the sequence of the invoice it credits, and its credit_note.* checks (see the create operation) run again on every draft edit and at finalize.

paid is refused: an invoice becomes paid by recording a payment against it.

{"status": "cancelled"} is refused with 409 while live payment allocations stand against the invoice. Cancelling an issued credit note gives its amount back to the invoice it credits; a credit note that changed meanwhile returns 409 credit_note.cancel_conflict.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null
Reference (object) or null

Re-pick the issuing Company. Validated against the tenant's per-doc-type allowed list. Only editable while the invoice is in draft. Per the no-bare-id rule the wire shape is the full Reference object.

Reference (object) or null

Re-pick the sales channel, or null to clear. Only editable while the invoice is in draft.

issue_date
string <date>
due_date
string <date>
dunning_level
integer >= 0

Dunning escalation level (0 = none, 1..N = reminder ladder step).

tax_point_date
string <date>
actual_delivery_date
string <date>
document_type_code
string
Enum: "380" "381" "384" "386" "326"
currency
string = 3 characters
buyer_reference
string

EN 16931 BT-10. Left out of a PATCH that changes business_partner, it is taken from the new partner's identifiers, as on a create.

purchase_order_reference
string

EN 16931 BT-13. Left out of a PATCH that changes business_partner, the new partner's purchase_order_reference is taken.

contract_reference
string
project_reference
string
subject
string or null
object (InvoicePeriod)

Invoice-level invoicing period (EN 16931 BG-14).

object (InvoiceBillingReference)

Preceding-invoice reference (EN 16931 BG-3 / BT-25 / BT-26).

buyer_name
string
buyer_legal_registration_id
string
buyer_identifier
string
buyer_identifier_scheme_id
string or null

EN 16931 BT-46-1 — ISO/IEC 6523 scheme of buyer_identifier.

buyer_customer_number
string or null
buyer_vat_id
string
buyer_vat_id_type
string

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb).

object (InvoicePartyContact)

Contact group (EN 16931 BG-6 / BG-9).

object (InvoiceElectronicAddress)

EN 16931 BT-49. Left out of a PATCH that changes business_partner, the new partner's is taken.

object (InvoicePayee)

Third-party payee (EN 16931 BG-10). Populated only when the party receiving payment differs from the seller (e.g. factoring).

payment_means_code
string
payment_terms_text
string
InvoicePaymentTerms (object) or null
remittance_information
string
Array of objects (InvoiceLineItemCreate)
notes
Array of strings or null

Replaces the persisted list. null / omitted = no change; [] clears the field.

show_gross_values_per_line_item
boolean

Whether each line shows its value with VAT included (true) or net of VAT (false). Omitted on create, the invoice takes the default_show_gross_values_per_line_item of its invoice type. Draft only; changing it recalculates the lines from their prices as entered and never changes a price. A credit note always takes the value of the invoice it credits.

prepaid_amount
number >= 0

EN 16931 BT-113: an amount already paid, in the invoice's currency, taken off the amount payable. Draft only. Defaults to 0. More than tax_inclusive + rounding_amount is a 422.

status
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
type_id
string or null
schema_version
string or null
object
object or null

The slots sent replace the whole address map, each stored in full with any part left out as null. addresses: null is ignored.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "dunning_level": 0,
  • "tax_point_date": "2019-08-24",
  • "actual_delivery_date": "2019-08-24",
  • "document_type_code": "380",
  • "currency": "str",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "subject": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_identifier_scheme_id": "string",
  • "buyer_customer_number": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_means_code": "string",
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [
    ],
  • "show_gross_values_per_line_item": true,
  • "prepaid_amount": 0,
  • "status": "draft",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    }
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Partially update invoice fields and/or status

{"status": "finalized"} issues the invoice: it refreshes the seller snapshot, re-rates VAT at the time of supply, stamps the number from the tenant's numbering schema in the same atomic write, and hands the PDF off to the document generator. A finalize carries no other field changes — save the edits first — and only a draft can be finalized.

A credit note is numbered in the sequence of the invoice it credits, and its credit_note.* checks (see the create operation) run again on every draft edit and at finalize.

paid is refused: an invoice becomes paid by recording a payment against it.

{"status": "cancelled"} is refused with 409 while live payment allocations stand against the invoice. Cancelling an issued credit note gives its amount back to the invoice it credits; a credit note that changed meanwhile returns 409 credit_note.cancel_conflict.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null
Reference (object) or null

Re-pick the issuing Company. Validated against the tenant's per-doc-type allowed list. Only editable while the invoice is in draft. Per the no-bare-id rule the wire shape is the full Reference object.

Reference (object) or null

Re-pick the sales channel, or null to clear. Only editable while the invoice is in draft.

issue_date
string <date>
due_date
string <date>
dunning_level
integer >= 0

Dunning escalation level (0 = none, 1..N = reminder ladder step).

tax_point_date
string <date>
actual_delivery_date
string <date>
document_type_code
string
Enum: "380" "381" "384" "386" "326"
currency
string = 3 characters
buyer_reference
string

EN 16931 BT-10. Left out of a PATCH that changes business_partner, it is taken from the new partner's identifiers, as on a create.

purchase_order_reference
string

EN 16931 BT-13. Left out of a PATCH that changes business_partner, the new partner's purchase_order_reference is taken.

contract_reference
string
project_reference
string
subject
string or null
object (InvoicePeriod)

Invoice-level invoicing period (EN 16931 BG-14).

object (InvoiceBillingReference)

Preceding-invoice reference (EN 16931 BG-3 / BT-25 / BT-26).

buyer_name
string
buyer_legal_registration_id
string
buyer_identifier
string
buyer_identifier_scheme_id
string or null

EN 16931 BT-46-1 — ISO/IEC 6523 scheme of buyer_identifier.

buyer_customer_number
string or null
buyer_vat_id
string
buyer_vat_id_type
string

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb).

object (InvoicePartyContact)

Contact group (EN 16931 BG-6 / BG-9).

object (InvoiceElectronicAddress)

EN 16931 BT-49. Left out of a PATCH that changes business_partner, the new partner's is taken.

object (InvoicePayee)

Third-party payee (EN 16931 BG-10). Populated only when the party receiving payment differs from the seller (e.g. factoring).

payment_means_code
string
payment_terms_text
string
InvoicePaymentTerms (object) or null
remittance_information
string
Array of objects (InvoiceLineItemCreate)
notes
Array of strings or null

Replaces the persisted list. null / omitted = no change; [] clears the field.

show_gross_values_per_line_item
boolean

Whether each line shows its value with VAT included (true) or net of VAT (false). Omitted on create, the invoice takes the default_show_gross_values_per_line_item of its invoice type. Draft only; changing it recalculates the lines from their prices as entered and never changes a price. A credit note always takes the value of the invoice it credits.

prepaid_amount
number >= 0

EN 16931 BT-113: an amount already paid, in the invoice's currency, taken off the amount payable. Draft only. Defaults to 0. More than tax_inclusive + rounding_amount is a 422.

status
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
type_id
string or null
schema_version
string or null
object
object or null

The slots sent replace the whole address map, each stored in full with any part left out as null. addresses: null is ignored.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "dunning_level": 0,
  • "tax_point_date": "2019-08-24",
  • "actual_delivery_date": "2019-08-24",
  • "document_type_code": "380",
  • "currency": "str",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "subject": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_identifier_scheme_id": "string",
  • "buyer_customer_number": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_means_code": "string",
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [
    ],
  • "show_gross_values_per_line_item": true,
  • "prepaid_amount": 0,
  • "status": "draft",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    }
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Cancel an invoice (soft-delete; status → cancelled)

A finalized invoice carrying live payment allocations returns 409. Void the allocations first, then cancel it. Cancelling an issued credit note gives its amount back to the invoice it credits; a credit note that changed meanwhile returns 409 credit_note.cancel_conflict.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Record a tax authority's clearance outcome for an invoice

The callback half of clearance. In Kenya, Nigeria, India and Brazil the tax authority must mint an artefact — an IRN, control number, cryptographic stamp or QR — before the document is a valid invoice at all, and Nigeria's turnaround is measured in hours. So the call to the authority never happens in a request: finalize hands off, a per-country worker service does the talking, and the answer arrives here, exactly as the VAT-ID validator reports an identifier validation.

Called by a worker holding a service identity, not by a user.

status is never touched by this endpoint. Clearance lives on its own axis so a clearance worker and the dunning worker are not two writers on one field.

Cleared is terminal. A repeated cleared returns the unchanged invoice; a rejected after a cleared is a 409. At-least-once delivery must not let message ordering decide whether an invoice is valid.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
status
required
string
Enum: "cleared" "rejected"
scheme
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which regime is reporting, as a code — never an authority name and never a display label.

Optional on the wire so an adapter written against the original callback contract keeps working, and immutable once recorded: a result naming a different regime than the one already on the invoice is refused with 409 rather than applied, because which regime cleared a document is a fact about the document and two regimes claiming one invoice is a routing bug upstream.

reference
string or null
stamp
string or null
qr
string or null
error
string or null

Why the authority refused. Expected whenever status is rejected.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "status": "cleared",
  • "scheme": "ke_kra_etims",
  • "reference": "IRN-2026-000123",
  • "stamp": "string",
  • "qr": "string",
  • "error": "string"
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

List the messages sent about an invoice

One row per send attempt per channel, newest first — the answer to "has this invoice gone out, where to, and when".

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (CorrespondenceResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Send an invoice to the business partner over a channel

Sending creates a correspondence row: two sends are two rows, which is why this is a creation and not a status change on the invoice.

The send itself is performed by an event-driven worker, so a 202 means "accepted for sending", not "sent" — poll GET /resource/v1/invoices/{invoice_id}/correspondence (or the row's _links.self) until status leaves queued.

The invoice must have left draft (it needs its number and frozen seller snapshot), and the business partner must have an email address — the one flagged for invoicing, else the primary one, else the only one. The invoice's own status is unchanged by a send; correspondence rows are the record of what went out.

Sending an invoice that already went out sends it again and creates a second row. One 409 is a send still in flight: while a row on the same channel is queued, a repeat is the same send twice, not a second one (reason: send_in_flight).

The send goes out as the draft named in email: the draft moves to queued in the same write as the row, and the row only points at it. A draft that was already sent answers 409 with reason: already_sent. Without email, a draft with the standard text is created and sent.

A reply draft (POST /resource/v1/emails/{id}/replies) named in email answers 422 with reason: reply_sent_from_its_email, before any check of the invoice, and nothing is queued: a reply is sent with PATCH /resource/v1/emails/{id} {"status": "queued"}.

Every send, reply and payment reminder counts against the daily limit of outgoing emails in the tenant's plan (20 per UTC day on every plan). Over it the send answers 429 with reason: tenant_outbound_cap_reached and nothing is queued; a refused or repeated send does not count. Two sends at the same moment can collide on that count; one that still collides after two retries answers 409 asking to send it again.

One email goes to at most 10 addresses in To and Cc together. A draft with more answers 422 with reason: too_many_recipients and nothing is queued or counted.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
channel
required
string (CorrespondenceChannel)
Value: "email"

Channel a document is sent over. email is the only value at MVP; the enum exists so adding a channel (e.g. WhatsApp) is an added member rather than a new endpoint.

acknowledge_uncleared
boolean
Default: false

Send even though the invoice has not been cleared by the tax authority. Staying compliant is the tenant's own legal responsibility, so an uncleared send is warned about (409 with invoice_not_cleared) rather than blocked outright; set this to acknowledge that responsibility and send the invoice anyway.

Reference (object) or null

The draft to send, from POST .../email-drafts. It must be a draft of this document; it moves to queued and its recipients, subject and body are what goes out. A draft that was already sent answers 409 with reason: already_sent. Omitted, a draft with the standard text is created and sent.

dedupe_key
string or null [ 1 .. 64 ] characters

Optional. A second send with the same key within the tenant sends nothing and returns the row the first one queued, as it now reads. The key is stored on the row. The repeated body is not compared with it. A key already used for another kind of record or another document is a 409.

Responses

Request samples

Content type
application/json
{
  • "channel": "email",
  • "acknowledge_uncleared": false,
  • "email": {
    },
  • "dedupe_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "cor_a1b2c3d4e5f6789012345",
  • "_class": "correspondence",
  • "document": {
    },
  • "channel": "email",
  • "purpose": "invoice",
  • "status": "queued",
  • "recipient": "billing@example.com",
  • "attachment": {
    },
  • "email_message": {
    },
  • "dedupe_key": "string",
  • "sent_at": 0,
  • "failure_reason": "string",
  • "thread_token": "Xk2v9QbWm1Lr",
  • "message": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "_links": {
    },
  • "created_by": {
    }
}

Read one message sent about an invoice

The row's own _links.self. Poll it while status is queued to learn whether the send succeeded.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
correspondence_id
required
string
Example: cor_a1b2c3d4e5f6789012345

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

The document this message is about — an invoice or an offer.

channel
required
string (CorrespondenceChannel)
Value: "email"

Channel a document is sent over. email is the only value at MVP; the enum exists so adding a channel (e.g. WhatsApp) is an added member rather than a new endpoint.

purpose
required
string (CorrespondencePurpose)
Enum: "invoice" "reminder" "offer"

What went out. invoice is the invoice itself and offer the offer itself, each carrying its own PDF; reminder is a dunning payment reminder chasing an invoice, carrying the approved message in the body and the same invoice PDF as its attachment. A document may only have one send in flight per channel; reminders repeat as the dunning ladder escalates.

status
required
string (CorrespondenceStatus)
Enum: "queued" "sent" "failed"

Lifecycle state, read from the email the row was sent as. A send starts at queued; the send worker moves its email to sent once the channel accepted it, or to failed with a failure_reason when the channel rejected it permanently, its outcome was never confirmed, or no worker started it. A failed row does not block a fresh send attempt.

recipient
required
string

Resolved destination for this channel — for email, the business partner's invoicing address at the moment the send was requested.

message
required
string or null

The approved reminder text sent in the body, for a reminder row; null for an invoice or offer row, whose body is generated from the document.

required
Reference (object) or null

The PDF file that actually went out, read from the email. null until the row is sent — which document is attached is decided at send time, so a regenerated PDF is the one the customer receives.

required
Reference (object) or null

The stored outbound message the send goes out as, linked when the send is queued. The row's status, sent_at, failure_reason, attachment and thread_token are read from it. Set for every send.

dedupe_key
required
string or null [ 1 .. 64 ] characters

The dedupe_key the send was made with; null when it carried none.

sent_at
required
integer or null

Unix seconds the channel accepted the message, read from the email; null until then.

failure_reason
required
string or null

Why a failed row failed, read from the email: the channel's error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null otherwise.

thread_token
required
string or null <= 32 characters

Random sub-address minted with the email, read from it. With a tenant alias the send's Reply-To is {alias}+{thread_token}@rccn.io, and a reply delivered to it follows the newest email sent under the token: it is linked to that email's document, or to nothing when the email has none. It carries no tenant or document data and authorises nothing: the alias decides the tenant, and the token is looked up only inside it. null on a row queued before threading existed.

created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object

self is the row's own URL — the one to poll while status is queued.

required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "cor_a1b2c3d4e5f6789012345",
  • "_class": "correspondence",
  • "document": {
    },
  • "channel": "email",
  • "purpose": "invoice",
  • "status": "queued",
  • "recipient": "billing@example.com",
  • "attachment": {
    },
  • "email_message": {
    },
  • "dedupe_key": "string",
  • "sent_at": 0,
  • "failure_reason": "string",
  • "thread_token": "Xk2v9QbWm1Lr",
  • "message": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "_links": {
    },
  • "created_by": {
    }
}

Create the draft email that sends this invoice

Stores a new outbound email in draft, linked to the invoice, with the recipients, subject and body a send would use, and returns it with the PDF it will attach. Edit it with PATCH /resource/v1/emails/{id}, send it with POST /resource/v1/invoices/{invoice_id}/correspondence naming it in email, or throw it away with DELETE /resource/v1/emails/{id}. A draft nobody edits expires after 30 days.

With email in the body, reopens that kept draft of this invoice instead (200); anything that is no longer a draft answers 409. A reply draft answers 422 with reason: reply_sent_from_its_email: it is sent with PATCH /resource/v1/emails/{id}.

A new draft is written by the agent off the request path, so it comes back drafting; follow the row (reopen it with email) until it is draft. When the agent cannot write it — past the tenant's agent allowance, no queue, a failed call — the template text is used and the row ends draft with generator: template, at once when it could not be queued. Sending never waits on it.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
optional
Reference (object) or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object (EmailBody)
generator
required
string or null
Enum: "template" "agent" null

What wrote the draft. template is a fixed text per document kind in the document's language, written in the request, so the draft comes back as draft. agent writes from the tenant's tone and the mail about the document, off the request path: a new draft comes back drafting; follow the row until it is draft. When the agent cannot write it (past the allowance, a failed call, a text that fails the checks), the row ends as a template draft.

required
Array of objects (Reference)

The earlier emails about the document the agent was given to write this draft, oldest first. Empty for a template draft and while the draft is drafting. Set by the server; _name is the email's subject as it was when the draft was written.

pdf_status
required
string
Enum: "ready" "pending" "failed"

pending covers a render still running and a document with no PDF yet; a send still goes ahead and the send worker waits for the PDF. failed means every render failed, and the document cannot be sent until one succeeds.

attachment_name
required
string

File name the PDF goes out under.

required
EmailDraftAttachment (object) or null

The rendered PDF; null while pdf_status is not ready.

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object (EmailBody)
generator
required
string or null
Enum: "template" "agent" null

What wrote the draft. template is a fixed text per document kind in the document's language, written in the request, so the draft comes back as draft. agent writes from the tenant's tone and the mail about the document, off the request path: a new draft comes back drafting; follow the row until it is draft. When the agent cannot write it (past the allowance, a failed call, a text that fails the checks), the row ends as a template draft.

required
Array of objects (Reference)

The earlier emails about the document the agent was given to write this draft, oldest first. Empty for a template draft and while the draft is drafting. Set by the server; _name is the email's subject as it was when the draft was written.

pdf_status
required
string
Enum: "ready" "pending" "failed"

pending covers a render still running and a document with no PDF yet; a send still goes ahead and the send worker waits for the PDF. failed means every render failed, and the document cannot be sent until one succeeds.

attachment_name
required
string

File name the PDF goes out under.

required
EmailDraftAttachment (object) or null

The rendered PDF; null while pdf_status is not ready.

Request samples

Content type
application/json
{
  • "email": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "body": {
    },
  • "draft_context": [
    ],
  • "generator": "template",
  • "pdf_status": "ready",
  • "attachment_name": "invoice-RE-2026-0142.pdf",
  • "pdf": {
    }
}

Refresh invoice address snapshots from the partner's preferred addresses

Replaces the invoice's address snapshots with the current preferred (primary) addresses from the linked business partner, for every slot declared on the invoice type. The frontend calls this after the user confirms a "Update addresses to {new partner}'s defaults?" prompt triggered by a business-partner change. Only allowed while the invoice is in draft.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

List the invoice's line items

The same rows the invoice itself returns in line_items, at the URL the invoice advertises as _links.line_items. Unpaginated — next_token is always null — because a line array is bounded by what fits on one invoice.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (InvoiceLineItemResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Append a line item to an invoice

Sub-resource sugar over the parent invoice update: the invoice's totals and VAT breakdown are recomputed and one DynamoDB item is written, as if the whole line_items array had been sent.

Draft only. An invoice that has been finalized or cancelled answers 422 — an issued invoice is the legal record and its content is frozen.

The line is new by definition, so a body carrying _id is a 422 — the server assigns line ids. To change an existing line, address its own URL.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
required
number or string (Decimal)
_id
string

The id of a line already on this invoice, when the intent is to edit that line rather than add one. Omit it to add a line — the server assigns the id. An _id naming no line on the invoice is a 422; ids are the server's and a client may not invent one.

description
string non-empty
(Decimal (Decimal (number) or Decimal (string))) or null

Optional. Filled by the resolver when product is supplied alone.

unit_price_is_gross
boolean or null

Whether unit_price includes VAT; only with a unit_price, else 422. Omitted, a typed price is net. A catalogue price keeps the flag it is quoted with. Either kind of price can sit on a document showing gross or net values; it is converted with the line's own rate.

vat_category
string or null
Enum: "S" "Z" "E" null

The supply's VAT category (UNCL 5305): S taxed, Z zero-rated, E exempt. Omit it and vat_rate_class — the default — to inherit the product's, then the tenant's vat.default_vat_category. Set, they override that for this line only; the regime and the rate are still resolved from them against the supply and target countries and the date. The regime codes (AE, K, G, O) are applied by the resolver and refused here.

The rate itself is never accepted on input; it is looked up per country and date, and which rate classes a country has varies.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S the line takes. Set exactly when vat_category is S; any other combination is a 422.

Reference (object) or null

Reference to the catalog product whose price should be applied to this line. When set without an explicit unit_price, the invoice service auto-fills unit_price and unit_price_is_gross from the resolver result.

unit_code
string or null [ 1 .. 3 ] characters ^[A-Za-z0-9]{1,3}$

UN/ECE Recommendation 20 unit of measure (EN 16931 BT-130). Omit it to get C62 ("one"), which is what every line issued before this field existed reads back as. Any syntactically valid Rec 20 code is accepted, not just the shortlist the UI offers — a trade we did not anticipate must not be blocked by our list. Lower case is upper-cased on write.

InvoiceItemClassification (object) or null
Reference (object) or null

Credit note only: the line of the credited invoice this line credits, as {"_id": "<line id>"}. The line then takes that line's price, VAT, product and unit, and its stored net and gross scaled to quantity; only quantity and description are read from the request. The quantity must be above 0 and at most what earlier issued credit notes left of the line. The credit note that takes the last of a line takes exactly what is left of its figures, and the one that takes the last of a VAT group takes what is left of the group's VAT, so the credit notes of an invoice add up to it.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "line_item"
required
object

self is the line's own resource URL, under the invoice that owns it. It survives an edit: a line id is the server's and is kept when a caller round-trips it.

description
required
string
required
number or string (Decimal)
required
number or string (Decimal)
unit_price_is_gross
required
boolean

Whether unit_price includes VAT.

vat_regime
required
string
Enum: "domestic_vat" "intra_eu_reverse_charge" "intra_eu_oss" "intra_eu_origin_b2c" "third_country_export" "destination_sales_tax" "exempt"

The VAT regime the resolver picked at issue time. Snapshotted — a historical invoice keeps the treatment that applied when it was issued, even after the countries involved change bloc membership.

vat_country
required
string or null = 2 characters

ISO 3166-1 alpha-2 country whose VAT regime applied.

vat_category
required
string
Enum: "S" "Z" "E" "AE" "K" "G" "O" "L" "M"

UNCL 5305 code of the line (BT-151), with the regime applied: AE reverse charge, K intra-EU supply of goods, G export, O outside the scope of VAT, E exempt.

vat_category_source
required
string
Enum: "line" "product" "tenant_default"

Where the category came from — a deliberate per-line choice, the product's default, or the tenant's. Recorded so an audit can tell a chosen band from an inherited one without re-deriving anything.

required
number or string (Decimal)
vat_legal_note
required
string or null

Localised note the invoice must print for this regime (e.g. the reverse-charge or export wording), in the tenant's language with English as the fallback. Null when the regime needs no note.

required
number or string (Decimal)
required
number or string (Decimal)
line_total_gross
required
number or null

Quantity × the gross unit price, rounded. Set exactly when the document shows gross values per line, null otherwise.

required
Reference (object) or null

Back-link to the catalog product the line was priced from, when applicable.

resolved_price_id
required
string or null

Id of the ProductPrice row the resolver chose, when the line was priced by the multi-dimension resolver. Always null in single-price mode and when the caller supplied an explicit unit_price.

required
Reference (object) or null

On a credit note, the line of the credited invoice this line credits; null on a line that credits none, and on every other document.

unit_code
required
string [ 1 .. 3 ] characters ^[A-Z0-9]{1,3}$

UN/ECE Rec 20 unit of measure (BT-130). Never null — a line with no unit is not exportable, so the default C62 is written instead.

unit_label
required
string

unit_code written out for a reader, in the invoice's language and matched to this line's quantity (1 day vs 2 days) — the same word the PDF prints, so a screen and the document it represents never disagree. Read-only and backend-composed; rendered on read rather than stored, so it is not accepted on input and carries no history.

Empty for C62 ("one"): "12 × Sourdough" reads better than "12 Piece × Sourdough". A code outside the shortlist renders as the code itself rather than as nothing — showing it tells the reader something, dropping it would misstate the line.

required
InvoiceItemClassification (object) or null
seller_item_identifier
required
string or null

The seller's own article number (BT-155), snapshotted from the product's sku identifier at issue time. Null when the line carries no product, or the product has no SKU.

required
InvoiceStandardItemIdentifier (object) or null

Snapshotted from the product's gtin at issue time (BT-157). GTIN is the only source: BT-157 identifies the article, and the other product-applicable schemes are not article identifiers in a scheme a receiver can resolve.

required
Array of objects (PrintedIdentifier)

The numbers this line prints beside its description, snapshotted from the product's primary identifiers when the line was written. Which ones print is the product type's decision (primary on its identifier declarations); the pair is stored rather than a joined string so it can be re-ordered and exported. Distinct from BT-155 / BT-157 above, which are the EN 16931 export slots and take only sku / gtin.

supply_kind
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

What the line supplies, from its product (else the product's type). Null for a line without a product or a supply kind. Decides K (goods) or AE on an intra-EU reverse-charge line.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Request samples

Content type
application/json
{
  • "_id": "li_a1b2c3d4e5f6",
  • "description": "Consulting services",
  • "quantity": 0,
  • "unit_price": 0,
  • "unit_price_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "product": {
    },
  • "unit_code": "HUR",
  • "item_classification": {
    },
  • "credited_line_item": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "li_a1b2c3d4e5f6",
  • "_class": "line_item",
  • "_links": {
    },
  • "description": "Consulting services",
  • "quantity": 0,
  • "unit_price": 0,
  • "unit_price_is_gross": true,
  • "vat_regime": "domestic_vat",
  • "vat_country": "st",
  • "supply_kind": "goods",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "vat_category_source": "line",
  • "vat_rate_percent": 0,
  • "vat_legal_note": "string",
  • "unit_price_net": 0,
  • "line_total": 0,
  • "line_total_gross": 0,
  • "unit_code": "HUR",
  • "unit_label": "h",
  • "item_classification": {
    },
  • "seller_item_identifier": "SD-100",
  • "standard_item_identifier": {
    },
  • "item_identifiers": [
    ],
  • "product": {
    },
  • "credited_line_item": {
    },
  • "resolved_price_id": "string"
}

Get one line item

A line is an object with an id, so it answers at its own URL — the one every line carries as _links.self. 404 when this invoice does not hold that line, including when it belongs to another invoice.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
line_item_id
required
string
Example: li_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "line_item"
required
object

self is the line's own resource URL, under the invoice that owns it. It survives an edit: a line id is the server's and is kept when a caller round-trips it.

description
required
string
required
number or string (Decimal)
required
number or string (Decimal)
unit_price_is_gross
required
boolean

Whether unit_price includes VAT.

vat_regime
required
string
Enum: "domestic_vat" "intra_eu_reverse_charge" "intra_eu_oss" "intra_eu_origin_b2c" "third_country_export" "destination_sales_tax" "exempt"

The VAT regime the resolver picked at issue time. Snapshotted — a historical invoice keeps the treatment that applied when it was issued, even after the countries involved change bloc membership.

vat_country
required
string or null = 2 characters

ISO 3166-1 alpha-2 country whose VAT regime applied.

vat_category
required
string
Enum: "S" "Z" "E" "AE" "K" "G" "O" "L" "M"

UNCL 5305 code of the line (BT-151), with the regime applied: AE reverse charge, K intra-EU supply of goods, G export, O outside the scope of VAT, E exempt.

vat_category_source
required
string
Enum: "line" "product" "tenant_default"

Where the category came from — a deliberate per-line choice, the product's default, or the tenant's. Recorded so an audit can tell a chosen band from an inherited one without re-deriving anything.

required
number or string (Decimal)
vat_legal_note
required
string or null

Localised note the invoice must print for this regime (e.g. the reverse-charge or export wording), in the tenant's language with English as the fallback. Null when the regime needs no note.

required
number or string (Decimal)
required
number or string (Decimal)
line_total_gross
required
number or null

Quantity × the gross unit price, rounded. Set exactly when the document shows gross values per line, null otherwise.

required
Reference (object) or null

Back-link to the catalog product the line was priced from, when applicable.

resolved_price_id
required
string or null

Id of the ProductPrice row the resolver chose, when the line was priced by the multi-dimension resolver. Always null in single-price mode and when the caller supplied an explicit unit_price.

required
Reference (object) or null

On a credit note, the line of the credited invoice this line credits; null on a line that credits none, and on every other document.

unit_code
required
string [ 1 .. 3 ] characters ^[A-Z0-9]{1,3}$

UN/ECE Rec 20 unit of measure (BT-130). Never null — a line with no unit is not exportable, so the default C62 is written instead.

unit_label
required
string

unit_code written out for a reader, in the invoice's language and matched to this line's quantity (1 day vs 2 days) — the same word the PDF prints, so a screen and the document it represents never disagree. Read-only and backend-composed; rendered on read rather than stored, so it is not accepted on input and carries no history.

Empty for C62 ("one"): "12 × Sourdough" reads better than "12 Piece × Sourdough". A code outside the shortlist renders as the code itself rather than as nothing — showing it tells the reader something, dropping it would misstate the line.

required
InvoiceItemClassification (object) or null
seller_item_identifier
required
string or null

The seller's own article number (BT-155), snapshotted from the product's sku identifier at issue time. Null when the line carries no product, or the product has no SKU.

required
InvoiceStandardItemIdentifier (object) or null

Snapshotted from the product's gtin at issue time (BT-157). GTIN is the only source: BT-157 identifies the article, and the other product-applicable schemes are not article identifiers in a scheme a receiver can resolve.

required
Array of objects (PrintedIdentifier)

The numbers this line prints beside its description, snapshotted from the product's primary identifiers when the line was written. Which ones print is the product type's decision (primary on its identifier declarations); the pair is stored rather than a joined string so it can be re-ordered and exported. Distinct from BT-155 / BT-157 above, which are the EN 16931 export slots and take only sku / gtin.

supply_kind
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

What the line supplies, from its product (else the product's type). Null for a line without a product or a supply kind. Decides K (goods) or AE on an intra-EU reverse-charge line.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Response samples

Content type
application/json
{
  • "_id": "li_a1b2c3d4e5f6",
  • "_class": "line_item",
  • "_links": {
    },
  • "description": "Consulting services",
  • "quantity": 0,
  • "unit_price": 0,
  • "unit_price_is_gross": true,
  • "vat_regime": "domestic_vat",
  • "vat_country": "st",
  • "supply_kind": "goods",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "vat_category_source": "line",
  • "vat_rate_percent": 0,
  • "vat_legal_note": "string",
  • "unit_price_net": 0,
  • "line_total": 0,
  • "line_total_gross": 0,
  • "unit_code": "HUR",
  • "unit_label": "h",
  • "item_classification": {
    },
  • "seller_item_identifier": "SD-100",
  • "standard_item_identifier": {
    },
  • "item_identifiers": [
    ],
  • "product": {
    },
  • "credited_line_item": {
    },
  • "resolved_price_id": "string"
}

Replace one line item

Full replace: the body is the new content of the line, and the line id stays with it across the swap so the URL survives. A body _id that disagrees with the URL is a 422 rather than being silently overridden.

A PUT restates the line, so an explicit unit_price is read as net unless the line names a product — the same reading a create gets. Use PATCH to edit a gross-quoted line without restating its basis.

Draft only; see POST.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
line_item_id
required
string
Example: li_a1b2c3d4e5f6
Request Body schema: application/json
required
required
number or string (Decimal)
_id
string

The id of a line already on this invoice, when the intent is to edit that line rather than add one. Omit it to add a line — the server assigns the id. An _id naming no line on the invoice is a 422; ids are the server's and a client may not invent one.

description
string non-empty
(Decimal (Decimal (number) or Decimal (string))) or null

Optional. Filled by the resolver when product is supplied alone.

unit_price_is_gross
boolean or null

Whether unit_price includes VAT; only with a unit_price, else 422. Omitted, a typed price is net. A catalogue price keeps the flag it is quoted with. Either kind of price can sit on a document showing gross or net values; it is converted with the line's own rate.

vat_category
string or null
Enum: "S" "Z" "E" null

The supply's VAT category (UNCL 5305): S taxed, Z zero-rated, E exempt. Omit it and vat_rate_class — the default — to inherit the product's, then the tenant's vat.default_vat_category. Set, they override that for this line only; the regime and the rate are still resolved from them against the supply and target countries and the date. The regime codes (AE, K, G, O) are applied by the resolver and refused here.

The rate itself is never accepted on input; it is looked up per country and date, and which rate classes a country has varies.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S the line takes. Set exactly when vat_category is S; any other combination is a 422.

Reference (object) or null

Reference to the catalog product whose price should be applied to this line. When set without an explicit unit_price, the invoice service auto-fills unit_price and unit_price_is_gross from the resolver result.

unit_code
string or null [ 1 .. 3 ] characters ^[A-Za-z0-9]{1,3}$

UN/ECE Recommendation 20 unit of measure (EN 16931 BT-130). Omit it to get C62 ("one"), which is what every line issued before this field existed reads back as. Any syntactically valid Rec 20 code is accepted, not just the shortlist the UI offers — a trade we did not anticipate must not be blocked by our list. Lower case is upper-cased on write.

InvoiceItemClassification (object) or null
Reference (object) or null

Credit note only: the line of the credited invoice this line credits, as {"_id": "<line id>"}. The line then takes that line's price, VAT, product and unit, and its stored net and gross scaled to quantity; only quantity and description are read from the request. The quantity must be above 0 and at most what earlier issued credit notes left of the line. The credit note that takes the last of a line takes exactly what is left of its figures, and the one that takes the last of a VAT group takes what is left of the group's VAT, so the credit notes of an invoice add up to it.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "line_item"
required
object

self is the line's own resource URL, under the invoice that owns it. It survives an edit: a line id is the server's and is kept when a caller round-trips it.

description
required
string
required
number or string (Decimal)
required
number or string (Decimal)
unit_price_is_gross
required
boolean

Whether unit_price includes VAT.

vat_regime
required
string
Enum: "domestic_vat" "intra_eu_reverse_charge" "intra_eu_oss" "intra_eu_origin_b2c" "third_country_export" "destination_sales_tax" "exempt"

The VAT regime the resolver picked at issue time. Snapshotted — a historical invoice keeps the treatment that applied when it was issued, even after the countries involved change bloc membership.

vat_country
required
string or null = 2 characters

ISO 3166-1 alpha-2 country whose VAT regime applied.

vat_category
required
string
Enum: "S" "Z" "E" "AE" "K" "G" "O" "L" "M"

UNCL 5305 code of the line (BT-151), with the regime applied: AE reverse charge, K intra-EU supply of goods, G export, O outside the scope of VAT, E exempt.

vat_category_source
required
string
Enum: "line" "product" "tenant_default"

Where the category came from — a deliberate per-line choice, the product's default, or the tenant's. Recorded so an audit can tell a chosen band from an inherited one without re-deriving anything.

required
number or string (Decimal)
vat_legal_note
required
string or null

Localised note the invoice must print for this regime (e.g. the reverse-charge or export wording), in the tenant's language with English as the fallback. Null when the regime needs no note.

required
number or string (Decimal)
required
number or string (Decimal)
line_total_gross
required
number or null

Quantity × the gross unit price, rounded. Set exactly when the document shows gross values per line, null otherwise.

required
Reference (object) or null

Back-link to the catalog product the line was priced from, when applicable.

resolved_price_id
required
string or null

Id of the ProductPrice row the resolver chose, when the line was priced by the multi-dimension resolver. Always null in single-price mode and when the caller supplied an explicit unit_price.

required
Reference (object) or null

On a credit note, the line of the credited invoice this line credits; null on a line that credits none, and on every other document.

unit_code
required
string [ 1 .. 3 ] characters ^[A-Z0-9]{1,3}$

UN/ECE Rec 20 unit of measure (BT-130). Never null — a line with no unit is not exportable, so the default C62 is written instead.

unit_label
required
string

unit_code written out for a reader, in the invoice's language and matched to this line's quantity (1 day vs 2 days) — the same word the PDF prints, so a screen and the document it represents never disagree. Read-only and backend-composed; rendered on read rather than stored, so it is not accepted on input and carries no history.

Empty for C62 ("one"): "12 × Sourdough" reads better than "12 Piece × Sourdough". A code outside the shortlist renders as the code itself rather than as nothing — showing it tells the reader something, dropping it would misstate the line.

required
InvoiceItemClassification (object) or null
seller_item_identifier
required
string or null

The seller's own article number (BT-155), snapshotted from the product's sku identifier at issue time. Null when the line carries no product, or the product has no SKU.

required
InvoiceStandardItemIdentifier (object) or null

Snapshotted from the product's gtin at issue time (BT-157). GTIN is the only source: BT-157 identifies the article, and the other product-applicable schemes are not article identifiers in a scheme a receiver can resolve.

required
Array of objects (PrintedIdentifier)

The numbers this line prints beside its description, snapshotted from the product's primary identifiers when the line was written. Which ones print is the product type's decision (primary on its identifier declarations); the pair is stored rather than a joined string so it can be re-ordered and exported. Distinct from BT-155 / BT-157 above, which are the EN 16931 export slots and take only sku / gtin.

supply_kind
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

What the line supplies, from its product (else the product's type). Null for a line without a product or a supply kind. Decides K (goods) or AE on an intra-EU reverse-charge line.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Request samples

Content type
application/json
{
  • "_id": "li_a1b2c3d4e5f6",
  • "description": "Consulting services",
  • "quantity": 0,
  • "unit_price": 0,
  • "unit_price_is_gross": true,
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "product": {
    },
  • "unit_code": "HUR",
  • "item_classification": {
    },
  • "credited_line_item": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "li_a1b2c3d4e5f6",
  • "_class": "line_item",
  • "_links": {
    },
  • "description": "Consulting services",
  • "quantity": 0,
  • "unit_price": 0,
  • "unit_price_is_gross": true,
  • "vat_regime": "domestic_vat",
  • "vat_country": "st",
  • "supply_kind": "goods",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "vat_category_source": "line",
  • "vat_rate_percent": 0,
  • "vat_legal_note": "string",
  • "unit_price_net": 0,
  • "line_total": 0,
  • "line_total_gross": 0,
  • "unit_code": "HUR",
  • "unit_label": "h",
  • "item_classification": {
    },
  • "seller_item_identifier": "SD-100",
  • "standard_item_identifier": {
    },
  • "item_identifiers": [
    ],
  • "product": {
    },
  • "credited_line_item": {
    },
  • "resolved_price_id": "string"
}

Partially update one line item

Body is an arbitrary subset of InvoiceLineItemCreate fields. The service overlays the patch onto the stored line, re-validates the result and rebuilds the line, then recomputes the invoice's totals and VAT breakdown. A body _id that disagrees with the URL is a 422.

The line keeps the tax basis it was quoted in: patching the quantity of a gross-quoted line does not re-read its price as net.

Draft only; see POST.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
line_item_id
required
string
Example: li_a1b2c3d4e5f6
Request Body schema: application/json
required
property name*
additional property
any

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "line_item"
required
object

self is the line's own resource URL, under the invoice that owns it. It survives an edit: a line id is the server's and is kept when a caller round-trips it.

description
required
string
required
number or string (Decimal)
required
number or string (Decimal)
unit_price_is_gross
required
boolean

Whether unit_price includes VAT.

vat_regime
required
string
Enum: "domestic_vat" "intra_eu_reverse_charge" "intra_eu_oss" "intra_eu_origin_b2c" "third_country_export" "destination_sales_tax" "exempt"

The VAT regime the resolver picked at issue time. Snapshotted — a historical invoice keeps the treatment that applied when it was issued, even after the countries involved change bloc membership.

vat_country
required
string or null = 2 characters

ISO 3166-1 alpha-2 country whose VAT regime applied.

vat_category
required
string
Enum: "S" "Z" "E" "AE" "K" "G" "O" "L" "M"

UNCL 5305 code of the line (BT-151), with the regime applied: AE reverse charge, K intra-EU supply of goods, G export, O outside the scope of VAT, E exempt.

vat_category_source
required
string
Enum: "line" "product" "tenant_default"

Where the category came from — a deliberate per-line choice, the product's default, or the tenant's. Recorded so an audit can tell a chosen band from an inherited one without re-deriving anything.

required
number or string (Decimal)
vat_legal_note
required
string or null

Localised note the invoice must print for this regime (e.g. the reverse-charge or export wording), in the tenant's language with English as the fallback. Null when the regime needs no note.

required
number or string (Decimal)
required
number or string (Decimal)
line_total_gross
required
number or null

Quantity × the gross unit price, rounded. Set exactly when the document shows gross values per line, null otherwise.

required
Reference (object) or null

Back-link to the catalog product the line was priced from, when applicable.

resolved_price_id
required
string or null

Id of the ProductPrice row the resolver chose, when the line was priced by the multi-dimension resolver. Always null in single-price mode and when the caller supplied an explicit unit_price.

required
Reference (object) or null

On a credit note, the line of the credited invoice this line credits; null on a line that credits none, and on every other document.

unit_code
required
string [ 1 .. 3 ] characters ^[A-Z0-9]{1,3}$

UN/ECE Rec 20 unit of measure (BT-130). Never null — a line with no unit is not exportable, so the default C62 is written instead.

unit_label
required
string

unit_code written out for a reader, in the invoice's language and matched to this line's quantity (1 day vs 2 days) — the same word the PDF prints, so a screen and the document it represents never disagree. Read-only and backend-composed; rendered on read rather than stored, so it is not accepted on input and carries no history.

Empty for C62 ("one"): "12 × Sourdough" reads better than "12 Piece × Sourdough". A code outside the shortlist renders as the code itself rather than as nothing — showing it tells the reader something, dropping it would misstate the line.

required
InvoiceItemClassification (object) or null
seller_item_identifier
required
string or null

The seller's own article number (BT-155), snapshotted from the product's sku identifier at issue time. Null when the line carries no product, or the product has no SKU.

required
InvoiceStandardItemIdentifier (object) or null

Snapshotted from the product's gtin at issue time (BT-157). GTIN is the only source: BT-157 identifies the article, and the other product-applicable schemes are not article identifiers in a scheme a receiver can resolve.

required
Array of objects (PrintedIdentifier)

The numbers this line prints beside its description, snapshotted from the product's primary identifiers when the line was written. Which ones print is the product type's decision (primary on its identifier declarations); the pair is stored rather than a joined string so it can be re-ordered and exported. Distinct from BT-155 / BT-157 above, which are the EN 16931 export slots and take only sku / gtin.

supply_kind
string or null
Enum: "goods" "services" "digital_services" "intra_community_installation" null

What the line supplies, from its product (else the product's type). Null for a line without a product or a supply kind. Decides K (goods) or AE on an intra-EU reverse-charge line.

vat_rate_class
string or null
Enum: "standard" "reduced" "second_reduced" "super_reduced" "higher" null

Which rate of category S; set exactly when vat_category is S.

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "_id": "li_a1b2c3d4e5f6",
  • "_class": "line_item",
  • "_links": {
    },
  • "description": "Consulting services",
  • "quantity": 0,
  • "unit_price": 0,
  • "unit_price_is_gross": true,
  • "vat_regime": "domestic_vat",
  • "vat_country": "st",
  • "supply_kind": "goods",
  • "vat_category": "S",
  • "vat_rate_class": "standard",
  • "vat_category_source": "line",
  • "vat_rate_percent": 0,
  • "vat_legal_note": "string",
  • "unit_price_net": 0,
  • "line_total": 0,
  • "line_total_gross": 0,
  • "unit_code": "HUR",
  • "unit_label": "h",
  • "item_classification": {
    },
  • "seller_item_identifier": "SD-100",
  • "standard_item_identifier": {
    },
  • "item_identifiers": [
    ],
  • "product": {
    },
  • "credited_line_item": {
    },
  • "resolved_price_id": "string"
}

Remove one line item from an invoice

Recomputes the invoice's totals and VAT breakdown. Draft only; see POST.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
line_item_id
required
string
Example: li_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Offers

List offers (newest first)

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

status
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"
business_partner_id
string
type_id
string
offer_number
string

Only the offer carrying this number, ignoring letter case and surrounding whitespace. Answered from a lookup row written when the number is stamped, not from the search index, and returned in one page with a null next_token. A draft has no number and never matches. With q, it narrows the search hits instead.

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (OfferResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a new offer (starts as draft)

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

Reference (object) or null

Issuing Company (EN 16931 BG-7 Seller). Auto-resolved from the tenant's invoice-company config when omitted on create. Per the no-bare-id rule (architecture.md#Embedded References) the wire shape is the full Reference object.

Reference (object) or null

Optional tenant-defined sales channel selected for this offer. Snapshotted on the offer.

issue_date
string or null <date>
currency
string or null = 3 characters
buyer_reference
string or null

EN 16931 BT-10. Often the buyer's PO number or Leitweg-ID. Left out, the business partner's Leitweg-ID is used, else its number for us (partner_assigned_number); sent empty or null, the document has none.

purchase_order_reference
string or null

EN 16931 BT-13. Left out, the business partner's purchase_order_reference is used; sent empty or null, the document has none.

contract_reference
string or null

EN 16931 BT-12.

project_reference
string or null

EN 16931 BT-11.

subject
string or null

What the offer is about, printed as its subject line.

InvoicePeriod (object) or null
buyer_name
string or null

EN 16931 BT-44 — buyer name. Defaults to the partner's company/full name.

buyer_legal_registration_id
string or null

EN 16931 BT-47.

buyer_identifier
string or null

EN 16931 BT-46 — party identifier (GLN, DUNS, etc.). Defaults to the partner's GLN, together with buyer_identifier_scheme_id.

buyer_identifier_scheme_id
string or null

EN 16931 BT-46-1 — ISO/IEC 6523 scheme of buyer_identifier (0088 for a GLN). Taken with the identifier: when buyer_identifier is sent, this is what is sent beside it.

buyer_customer_number
string or null

The buyer's customer number with the seller (DIN 5008 Kundennummer). Defaults to the business partner's.

buyer_vat_id
string or null

EN 16931 BT-48.

buyer_vat_id_type
string or null

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb). Defaulted from the partner's VAT-class identifier when omitted.

InvoicePartyContact (object) or null
InvoiceElectronicAddress (object) or null

EN 16931 BT-49. Left out, the partner's Peppol ID is used (split into scheme and value), else its Leitweg-ID under scheme 0204; sent null, the document has none.

InvoicePayee (object) or null
payment_terms_text
string or null

EN 16931 BT-20.

InvoicePaymentTerms (object) or null

Structured skonto / late-payment block. Additive to BT-20 payment_terms_text — both render when supplied.

remittance_information
string or null

EN 16931 BT-83 — payment reference / Verwendungszweck.

Array of objects (InvoiceLineItemCreate)

The offer's positions. credited_line_item is for credit notes only; an offer refuses it with billing_document.credited_line_item_on_credit_note_only.

notes
Array of strings
Default: []

EN 16931 BT-22 — invoice notes (0..n). Each entry is rendered as its own paragraph below the totals. The author handles translation; the renderer prints what is supplied.

show_gross_values_per_line_item
boolean

Whether each line shows its value with VAT included (true) or net of VAT (false). Omitted on create, the offer takes the default_show_gross_values_per_line_item of its offer type. Draft only; changing it recalculates the lines from their prices as entered and never changes a price.

type_id
string [ 1 .. 100 ] characters

The offer-class tenant type this offer is created under. Every offer has one. It decides the letterhead and the payment defaults. Omitted, the offer is created under the tenant's default offer type; that is a 422 when the tenant has several and marks none of them default.

schema_version
string or null
object
Default: {}
object

Optional. When omitted, the server snapshots the partner's preferred addresses for each slot declared by the offer type. When supplied, the slot keys must be a subset of the offer type's address_slots.

valid_until
string <date>

Last day the quoted price stands. Defaults to issue_date + the tenant's offer.default_validity_days.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the offer number, or id while still a draft).

required
object

self is the offer's own resource URL. Its documents live under /resource/v1/offers/{id}/documents. Further rels may be present; a client follows the ones it knows.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"
issue_date
required
string <date>
currency
required
string
required
Array of objects (OfferLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the offer's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses.

required
object (MonetaryAmount)

EN 16931 BT-114. On an offer showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive + rounding_amount; an offer has no prepaid amount.

language
required
string

The language the offer is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the offer leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 notes (0..n), printed on the offer.

type_id
required
string

The tenant type this offer was created under.

required
object
required
object

Snapshotted address per slot the offer type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

offer_number
required
string

Empty ("") until the offer is finalized. Offer numbers are not gap-free.

valid_until
required
string or null <date>
required
Reference (object) or null

The offer this one replaces, when it is a revision.

accepted_at
required
integer or null

Unix seconds.

rejected_at
required
integer or null

Unix seconds.

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...), stored on the record itself.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this offer, null if none.

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2026-05-01",
  • "currency": "EUR",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "subject": "string",
  • "invoicing_period": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_identifier_scheme_id": "string",
  • "buyer_customer_number": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [ ],
  • "show_gross_values_per_line_item": true,
  • "type_id": "standard_offer",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    },
  • "valid_until": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "off_a1b2c3d4e5f6",
  • "_class": "offer",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "currency": "EUR",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "language": "de",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    },
  • "offer_number": "AN-2026-0001",
  • "valid_until": "2019-08-24",
  • "supersedes": {
    },
  • "accepted_at": 0,
  • "rejected_at": 0
}

List an offer's generated documents

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (OfferDocumentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Request the offer PDF

Writes the document in pdf_pending and publishes the event the generator subscribes to. The offer must have been finalized: a draft has no number, and a document with no number on it is not one to put in front of a customer.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
Request Body schema: application/json
optional
document_type
string (OfferDocumentType)
Value: "offer"

The kind of document. One today: the rendered offer PDF. It is an enum rather than a free string so a second artefact arrives as a deliberate change rather than by a caller inventing a value.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
offer_id
required
string
document_type
required
string (OfferDocumentType)
Value: "offer"

The kind of document. One today: the rendered offer PDF. It is an enum rather than a free string so a second artefact arrives as a deliberate change rather than by a caller inventing a value.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "document_type": "offer"
}

Response samples

Content type
application/json
{
  • "_id": "odoc_a1b2c3d4e5f6789012345",
  • "_class": "offer_document",
  • "offer_id": "off_a1b2c3d4e5f6",
  • "document_type": "offer",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Get one of an offer's documents

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
offer_document_id
required
string
Example: odoc_a1b2c3d4e5f6789012345

Responses

Response Schema: application/json
_id
required
string
_class
required
string
offer_id
required
string
document_type
required
string (OfferDocumentType)
Value: "offer"

The kind of document. One today: the rendered offer PDF. It is an enum rather than a free string so a second artefact arrives as a deliberate change rather than by a caller inventing a value.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "odoc_a1b2c3d4e5f6789012345",
  • "_class": "offer_document",
  • "offer_id": "off_a1b2c3d4e5f6",
  • "document_type": "offer",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Attach the rendered PDF, or retry a failed render

Setting file on a pdf_pending document moves it to pdf_ready. Idempotent: replaying on an already-attached document returns the PDF it already has. Setting status to pdf_pending re-requests the render of a failed document.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
offer_document_id
required
string
Example: odoc_a1b2c3d4e5f6789012345
Request Body schema: application/json
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
string
Value: "pdf_pending"

Set to pdf_pending to re-request a failed render. Idempotent for an already-pending row; 422 from any other status, and 422 when sent together with file — those are two different writes.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
offer_id
required
string
document_type
required
string (OfferDocumentType)
Value: "offer"

The kind of document. One today: the rendered offer PDF. It is an enum rather than a free string so a second artefact arrives as a deliberate change rather than by a caller inventing a value.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "file": {
    },
  • "status": "pdf_pending"
}

Response samples

Content type
application/json
{
  • "_id": "odoc_a1b2c3d4e5f6789012345",
  • "_class": "offer_document",
  • "offer_id": "off_a1b2c3d4e5f6",
  • "document_type": "offer",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Attach the rendered PDF, or retry a failed render

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
offer_document_id
required
string
Example: odoc_a1b2c3d4e5f6789012345
Request Body schema: application/json
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
string
Value: "pdf_pending"

Set to pdf_pending to re-request a failed render. Idempotent for an already-pending row; 422 from any other status, and 422 when sent together with file — those are two different writes.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
offer_id
required
string
document_type
required
string (OfferDocumentType)
Value: "offer"

The kind of document. One today: the rendered offer PDF. It is an enum rather than a free string so a second artefact arrives as a deliberate change rather than by a caller inventing a value.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "file": {
    },
  • "status": "pdf_pending"
}

Response samples

Content type
application/json
{
  • "_id": "odoc_a1b2c3d4e5f6789012345",
  • "_class": "offer_document",
  • "offer_id": "off_a1b2c3d4e5f6",
  • "document_type": "offer",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Delete a document and soft-delete its PDF

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
offer_document_id
required
string
Example: odoc_a1b2c3d4e5f6789012345

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List the messages sent about an offer

One row per send attempt per channel, newest first — the answer to "has this offer gone out, where to, and when".

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (CorrespondenceResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Send an offer to the business partner over a channel

The same sub-resource the invoice has, mounted on the offer: sending creates a correspondence row, so two sends are two rows.

The send itself is performed by an event-driven worker, so a 202 means "accepted for sending", not "sent" — poll GET /resource/v1/offers/{offer_id}/correspondence (or the row's _links.self) until status leaves queued.

The offer must have left draft (it needs its number and frozen seller snapshot), and the business partner must have an email address. The offer's own status is unchanged by a send — the rows are the record of what went out, which is also what tells a reopened offer whether it was ever sent.

One 409 is a send still in flight: while a row on the same channel is queued, a repeat is the same send twice, not a second one (reason: send_in_flight).

The send goes out as the draft named in email: the draft moves to queued in the same write as the row, and the row only points at it. A draft that was already sent answers 409 with reason: already_sent. Without email, a draft with the standard text is created and sent.

A reply draft (POST /resource/v1/emails/{id}/replies) named in email answers 422 with reason: reply_sent_from_its_email, before any check of the offer, and nothing is queued: a reply is sent with PATCH /resource/v1/emails/{id} {"status": "queued"}.

Every send, reply and payment reminder counts against the daily limit of outgoing emails in the tenant's plan (20 per UTC day on every plan). Over it the send answers 429 with reason: tenant_outbound_cap_reached and nothing is queued; a refused or repeated send does not count. Two sends at the same moment can collide on that count; one that still collides after two retries answers 409 asking to send it again.

One email goes to at most 10 addresses in To and Cc together. A draft with more answers 422 with reason: too_many_recipients and nothing is queued or counted.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
Request Body schema: application/json
required
channel
required
string (CorrespondenceChannel)
Value: "email"

Channel a document is sent over. email is the only value at MVP; the enum exists so adding a channel (e.g. WhatsApp) is an added member rather than a new endpoint.

acknowledge_uncleared
boolean
Default: false

Send even though the invoice has not been cleared by the tax authority. Staying compliant is the tenant's own legal responsibility, so an uncleared send is warned about (409 with invoice_not_cleared) rather than blocked outright; set this to acknowledge that responsibility and send the invoice anyway.

Reference (object) or null

The draft to send, from POST .../email-drafts. It must be a draft of this document; it moves to queued and its recipients, subject and body are what goes out. A draft that was already sent answers 409 with reason: already_sent. Omitted, a draft with the standard text is created and sent.

dedupe_key
string or null [ 1 .. 64 ] characters

Optional. A second send with the same key within the tenant sends nothing and returns the row the first one queued, as it now reads. The key is stored on the row. The repeated body is not compared with it. A key already used for another kind of record or another document is a 409.

Responses

Request samples

Content type
application/json
{
  • "channel": "email",
  • "acknowledge_uncleared": false,
  • "email": {
    },
  • "dedupe_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "cor_a1b2c3d4e5f6789012345",
  • "_class": "correspondence",
  • "document": {
    },
  • "channel": "email",
  • "purpose": "invoice",
  • "status": "queued",
  • "recipient": "billing@example.com",
  • "attachment": {
    },
  • "email_message": {
    },
  • "dedupe_key": "string",
  • "sent_at": 0,
  • "failure_reason": "string",
  • "thread_token": "Xk2v9QbWm1Lr",
  • "message": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "_links": {
    },
  • "created_by": {
    }
}

Read one message sent about an offer

The row's own _links.self. Poll it while status is queued to learn whether the send succeeded.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
correspondence_id
required
string
Example: cor_a1b2c3d4e5f6789012345

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

The document this message is about — an invoice or an offer.

channel
required
string (CorrespondenceChannel)
Value: "email"

Channel a document is sent over. email is the only value at MVP; the enum exists so adding a channel (e.g. WhatsApp) is an added member rather than a new endpoint.

purpose
required
string (CorrespondencePurpose)
Enum: "invoice" "reminder" "offer"

What went out. invoice is the invoice itself and offer the offer itself, each carrying its own PDF; reminder is a dunning payment reminder chasing an invoice, carrying the approved message in the body and the same invoice PDF as its attachment. A document may only have one send in flight per channel; reminders repeat as the dunning ladder escalates.

status
required
string (CorrespondenceStatus)
Enum: "queued" "sent" "failed"

Lifecycle state, read from the email the row was sent as. A send starts at queued; the send worker moves its email to sent once the channel accepted it, or to failed with a failure_reason when the channel rejected it permanently, its outcome was never confirmed, or no worker started it. A failed row does not block a fresh send attempt.

recipient
required
string

Resolved destination for this channel — for email, the business partner's invoicing address at the moment the send was requested.

message
required
string or null

The approved reminder text sent in the body, for a reminder row; null for an invoice or offer row, whose body is generated from the document.

required
Reference (object) or null

The PDF file that actually went out, read from the email. null until the row is sent — which document is attached is decided at send time, so a regenerated PDF is the one the customer receives.

required
Reference (object) or null

The stored outbound message the send goes out as, linked when the send is queued. The row's status, sent_at, failure_reason, attachment and thread_token are read from it. Set for every send.

dedupe_key
required
string or null [ 1 .. 64 ] characters

The dedupe_key the send was made with; null when it carried none.

sent_at
required
integer or null

Unix seconds the channel accepted the message, read from the email; null until then.

failure_reason
required
string or null

Why a failed row failed, read from the email: the channel's error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null otherwise.

thread_token
required
string or null <= 32 characters

Random sub-address minted with the email, read from it. With a tenant alias the send's Reply-To is {alias}+{thread_token}@rccn.io, and a reply delivered to it follows the newest email sent under the token: it is linked to that email's document, or to nothing when the email has none. It carries no tenant or document data and authorises nothing: the alias decides the tenant, and the token is looked up only inside it. null on a row queued before threading existed.

created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object

self is the row's own URL — the one to poll while status is queued.

required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "cor_a1b2c3d4e5f6789012345",
  • "_class": "correspondence",
  • "document": {
    },
  • "channel": "email",
  • "purpose": "invoice",
  • "status": "queued",
  • "recipient": "billing@example.com",
  • "attachment": {
    },
  • "email_message": {
    },
  • "dedupe_key": "string",
  • "sent_at": 0,
  • "failure_reason": "string",
  • "thread_token": "Xk2v9QbWm1Lr",
  • "message": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "_links": {
    },
  • "created_by": {
    }
}

Create the draft email that sends this offer

Stores a new outbound email in draft, linked to the offer, with the recipients, subject and body a send would use, and returns it with the PDF it will attach. Edit it with PATCH /resource/v1/emails/{id}, send it with POST /resource/v1/offers/{offer_id}/correspondence naming it in email, or throw it away with DELETE /resource/v1/emails/{id}. A draft nobody edits expires after 30 days.

With email in the body, reopens that kept draft of this offer instead (200); anything that is no longer a draft answers 409. A reply draft answers 422 with reason: reply_sent_from_its_email: it is sent with PATCH /resource/v1/emails/{id}.

A new draft is written by the agent off the request path, so it comes back drafting; follow the row (reopen it with email) until it is draft. When the agent cannot write it — past the tenant's agent allowance, no queue, a failed call — the template text is used and the row ends draft with generator: template, at once when it could not be queued. Sending never waits on it.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
Request Body schema: application/json
optional
Reference (object) or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object (EmailBody)
generator
required
string or null
Enum: "template" "agent" null

What wrote the draft. template is a fixed text per document kind in the document's language, written in the request, so the draft comes back as draft. agent writes from the tenant's tone and the mail about the document, off the request path: a new draft comes back drafting; follow the row until it is draft. When the agent cannot write it (past the allowance, a failed call, a text that fails the checks), the row ends as a template draft.

required
Array of objects (Reference)

The earlier emails about the document the agent was given to write this draft, oldest first. Empty for a template draft and while the draft is drafting. Set by the server; _name is the email's subject as it was when the draft was written.

pdf_status
required
string
Enum: "ready" "pending" "failed"

pending covers a render still running and a document with no PDF yet; a send still goes ahead and the send worker waits for the PDF. failed means every render failed, and the document cannot be sent until one succeeds.

attachment_name
required
string

File name the PDF goes out under.

required
EmailDraftAttachment (object) or null

The rendered PDF; null while pdf_status is not ready.

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object (EmailBody)
generator
required
string or null
Enum: "template" "agent" null

What wrote the draft. template is a fixed text per document kind in the document's language, written in the request, so the draft comes back as draft. agent writes from the tenant's tone and the mail about the document, off the request path: a new draft comes back drafting; follow the row until it is draft. When the agent cannot write it (past the allowance, a failed call, a text that fails the checks), the row ends as a template draft.

required
Array of objects (Reference)

The earlier emails about the document the agent was given to write this draft, oldest first. Empty for a template draft and while the draft is drafting. Set by the server; _name is the email's subject as it was when the draft was written.

pdf_status
required
string
Enum: "ready" "pending" "failed"

pending covers a render still running and a document with no PDF yet; a send still goes ahead and the send worker waits for the PDF. failed means every render failed, and the document cannot be sent until one succeeds.

attachment_name
required
string

File name the PDF goes out under.

required
EmailDraftAttachment (object) or null

The rendered PDF; null while pdf_status is not ready.

Request samples

Content type
application/json
{
  • "email": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "body": {
    },
  • "draft_context": [
    ],
  • "generator": "template",
  • "pdf_status": "ready",
  • "attachment_name": "invoice-RE-2026-0142.pdf",
  • "pdf": {
    }
}

Raise a draft invoice from an accepted offer

Accepting and invoicing are two acts: accepting is a status change and creates nothing, and the production or fulfilment flow sits between the two. One offer routinely becomes several invoices — a deposit and a final, or one per milestone — or none at all, so this may be called more than once and the offer is never mutated. The prices and terms the customer accepted are copied over exactly. VAT is re-rated at creation against the invoice date and the buyer, so a rate that has moved or a VAT-ID validated since the offer was written is reflected on the invoice.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
Request Body schema: application/json
optional
line_item_ids
Array of strings

Bill only these positions. Omitted, the whole offer is billed.

type_id
string

Raise the invoice under this invoice type. Omitted, the tenant's default invoice type is used. Must be a type of entity class invoice.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

required
object

self is the invoice's own resource URL; documents and line_items are its sub-collections. Further rels may be present; a client follows the ones it knows.

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
required
Reference (object) or null

The offer this invoice was raised from, null if none. One offer can produce several invoices — a deposit and a final, or one per milestone — so the link lives here and never as a list on the offer.

required
Reference (object) or null

On an issued credit note, the invoice it credits, stamped at finalize. Null on a draft and on every other document. Read-only.

payment_means_code
required
string
required
Array of objects (InvoiceLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

How much of the invoice has been settled — a second axis, derived from the recorded allocations and never accepted on input. It is deliberately separate from status: an invoice can be overdue and partially_paid at once, and folding the two together would give status a second writer alongside the dunning worker. Record a payment to change it; PATCH {status: "paid"} is rejected with 422.

required
object (MonetaryAmount)

Cash received against this invoice — the sum of its non-voided allocations. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

The part of the invoice its payments deliberately did not cover — withholding tax the customer remitted on the seller's behalf, an early-payment discount, bank charges. Backend-computed from the allocations' typed deductions.

required
object (MonetaryAmount)

The sum of the payable_amount of the issued, non-cancelled credit notes against this invoice. No further credit note may take it above tax_inclusive + rounding_amount. Backend-computed. Always carries the invoice currency, even at zero.

required
object (MonetaryAmount)

payable_amount − amount_paid − amount_written_off: what the invoice still owes. Computed on the wire, never stored. Withheld tax counts as settled because it is money the seller is no longer owed, even though it never reached the bank.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

clearance_status
required
string
Enum: "not_required" "pending" "cleared" "rejected"

Whether the tax authority has cleared this invoice — the third axis, beside status (lifecycle) and payment_status (settlement).

In a clearance market (Kenya, Nigeria, India, Brazil) the document is not a valid invoice until the authority mints its artefact, so pending and rejected both block sending. not_required is the default and covers every tenant not in such a market; whether a seller is in scope derives from the seller country, never from a field a user sets.

Deliberately not a sixth status value: that would give status a second unlocked writer racing the dunning worker.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

Which fiscal-clearance regime engaged, as a code — <country>_<authority>_<regime> in lower snake case.

Null whenever clearance_status is not_required, which is every invoice outside a clearance market. Set alongside pending, cleared and rejected: a rejected invoice still names the regime that refused it, because that is what makes the error actionable.

Read-only, and written only by a clearance adapter through POST /resource/v1/invoices/{id}/clearance. Never derived from the seller's country — clearance is a property of the clearing act, and a seller trading into two clearance markets would resolve to the wrong authority on an immutable document.

clearance_reference
required
string or null

The identity the authority minted — Nigeria's IRN, Kenya's Control Unit Invoice Number, India's IRN. Null until cleared.

clearance_stamp
required
string or null

Cryptographic signature where the authority issues one (Nigeria's CSID). Null where the regime issues none, and until cleared.

clearance_qr
required
string or null

QR payload the human-readable document must carry. Null until cleared.

cleared_at
required
integer or null

Unix seconds at which clearance was recorded. Null until cleared.

clearance_error
required
string or null

Why the authority refused, when clearance_status is rejected. Null otherwise.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses less prepaid_amount.

required
object (MonetaryAmount)

EN 16931 BT-113, the amount already paid. 0.00 unless set on the draft.

required
object (MonetaryAmount)

EN 16931 BT-114. On an invoice showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive − prepaid_amount + rounding_amount.

language
required
string

The language the invoice is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the invoice leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

type_id
required
string

The tenant type this invoice was created under.

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
object (MonetaryAmount)

tax_inclusive with its economic sign: negative on a credit note (381, 261), whose stored amounts stay positive. Add these, not tax_inclusive, when summing invoices. Computed on the wire.

required
object (MonetaryAmount)

amount_due with the same sign: on a credit note, the credit still to pay back as a negative figure.

required
Array of objects (InvoiceWarning)

Worked out on every read, never stored. Empty when there is nothing to say.

required
object (MonetaryAmount)

The same figure as amount_credited: the total of the issued, non-cancelled credit notes against this invoice. Zero on an invoice nobody credited and on a credit note.

required
object (MonetaryAmount)

What the customer still owes: max(0, payable_amount − amount_paid − amount_written_off − amount_credited). Zero on a credit note. A fully credited invoice keeps its status and payment_status; this figure is what says nothing is owed. Draft and cancelled credit notes do not reduce it.

required
Array of objects (InvoiceCreditNoteListing)

The issued, non-cancelled credit notes against this invoice. Listed from an index that can trail a just-issued credit note by a moment; amount_credited is stored on the invoice and is the figure to trust.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "line_item_ids": [
    ],
  • "type_id": "standard_invoice"
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "offer": {
    },
  • "credited_invoice": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "prepaid_amount": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "payment_status": "unpaid",
  • "amount_paid": {
    },
  • "amount_written_off": {
    },
  • "amount_credited": {
    },
  • "amount_due": {
    },
  • "signed_tax_inclusive": {
    },
  • "signed_amount_due": {
    },
  • "warnings": [
    ],
  • "credited": {
    },
  • "net_owed": {
    },
  • "credit_notes": [
    ],
  • "allocation_version": 0,
  • "clearance_status": "not_required",
  • "language": "de",
  • "clearance_scheme": "ke_kra_etims",
  • "clearance_reference": "IRN-2026-000123",
  • "clearance_stamp": "string",
  • "clearance_qr": "string",
  • "cleared_at": 0,
  • "clearance_error": "string",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Get offer by ID

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the offer number, or id while still a draft).

required
object

self is the offer's own resource URL. Its documents live under /resource/v1/offers/{id}/documents. Further rels may be present; a client follows the ones it knows.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"
issue_date
required
string <date>
currency
required
string
required
Array of objects (OfferLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the offer's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses.

required
object (MonetaryAmount)

EN 16931 BT-114. On an offer showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive + rounding_amount; an offer has no prepaid amount.

language
required
string

The language the offer is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the offer leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 notes (0..n), printed on the offer.

type_id
required
string

The tenant type this offer was created under.

required
object
required
object

Snapshotted address per slot the offer type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

offer_number
required
string

Empty ("") until the offer is finalized. Offer numbers are not gap-free.

valid_until
required
string or null <date>
required
Reference (object) or null

The offer this one replaces, when it is a revision.

accepted_at
required
integer or null

Unix seconds.

rejected_at
required
integer or null

Unix seconds.

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...), stored on the record itself.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this offer, null if none.

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "off_a1b2c3d4e5f6",
  • "_class": "offer",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "currency": "EUR",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "language": "de",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    },
  • "offer_number": "AN-2026-0001",
  • "valid_until": "2019-08-24",
  • "supersedes": {
    },
  • "accepted_at": 0,
  • "rejected_at": 0
}

Update offer fields and/or status

Fields may be changed only while the offer is a draft — once finalized, the customer holds that document. Moving the status to finalized stamps the offer number in the same write, and asks for the offer PDF: the document row is created afterwards and rendered in the background, so it is not on the response and a failure there does not undo the finalize. sent only records that the finalized offer went out. rejected back to sent reopens a declined offer: it keeps the number and the document and only clears rejected_at.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null
Reference (object) or null

Re-pick the issuing Company. Validated against the tenant's per-doc-type allowed list. Only editable while the offer is in draft. Per the no-bare-id rule the wire shape is the full Reference object.

Reference (object) or null

Re-pick the sales channel, or null to clear. Only editable while the offer is in draft.

issue_date
string <date>
currency
string = 3 characters
buyer_reference
string

EN 16931 BT-10. Left out of a PATCH that changes business_partner, it is taken from the new partner's identifiers, as on a create.

purchase_order_reference
string

EN 16931 BT-13. Left out of a PATCH that changes business_partner, the new partner's purchase_order_reference is taken.

contract_reference
string
project_reference
string
subject
string or null
object (InvoicePeriod)

Invoice-level invoicing period (EN 16931 BG-14).

buyer_name
string
buyer_legal_registration_id
string
buyer_identifier
string
buyer_identifier_scheme_id
string or null

EN 16931 BT-46-1 — ISO/IEC 6523 scheme of buyer_identifier.

buyer_customer_number
string or null
buyer_vat_id
string
buyer_vat_id_type
string

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb).

object (InvoicePartyContact)

Contact group (EN 16931 BG-6 / BG-9).

object (InvoiceElectronicAddress)

EN 16931 BT-49. Left out of a PATCH that changes business_partner, the new partner's is taken.

object (InvoicePayee)

Third-party payee (EN 16931 BG-10). Populated only when the party receiving payment differs from the seller (e.g. factoring).

payment_terms_text
string
InvoicePaymentTerms (object) or null
remittance_information
string
Array of objects (InvoiceLineItemCreate)

The offer's positions. credited_line_item is for credit notes only; an offer refuses it with billing_document.credited_line_item_on_credit_note_only.

notes
Array of strings or null

Replaces the persisted list. null / omitted = no change; [] clears the field.

status
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"

Moving to finalized stamps the offer number and asks for the PDF, which is rendered in the background — poll /offers/{offer_id}/documents for it. sent only records that the finalized offer went out; a finalized offer may also be answered without it. A rejected offer may go back to sent — reopening keeps the number and the document. expired and superseded are terminal.

show_gross_values_per_line_item
boolean

Whether each line shows its value with VAT included (true) or net of VAT (false). Omitted on create, the offer takes the default_show_gross_values_per_line_item of its offer type. Draft only; changing it recalculates the lines from their prices as entered and never changes a price.

type_id
string or null
schema_version
string or null
object
object or null

The slots sent replace the whole address map, each stored in full with any part left out as null. addresses: null is ignored.

valid_until
string <date>

Last day the quoted price stands. Defaults to issue_date + the tenant's offer.default_validity_days.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the offer number, or id while still a draft).

required
object

self is the offer's own resource URL. Its documents live under /resource/v1/offers/{id}/documents. Further rels may be present; a client follows the ones it knows.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"
issue_date
required
string <date>
currency
required
string
required
Array of objects (OfferLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the offer's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses.

required
object (MonetaryAmount)

EN 16931 BT-114. On an offer showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive + rounding_amount; an offer has no prepaid amount.

language
required
string

The language the offer is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the offer leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 notes (0..n), printed on the offer.

type_id
required
string

The tenant type this offer was created under.

required
object
required
object

Snapshotted address per slot the offer type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

offer_number
required
string

Empty ("") until the offer is finalized. Offer numbers are not gap-free.

valid_until
required
string or null <date>
required
Reference (object) or null

The offer this one replaces, when it is a revision.

accepted_at
required
integer or null

Unix seconds.

rejected_at
required
integer or null

Unix seconds.

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...), stored on the record itself.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this offer, null if none.

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2019-08-24",
  • "currency": "str",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "subject": "string",
  • "invoicing_period": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_identifier_scheme_id": "string",
  • "buyer_customer_number": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [
    ],
  • "status": "draft",
  • "show_gross_values_per_line_item": true,
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    },
  • "valid_until": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "off_a1b2c3d4e5f6",
  • "_class": "offer",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "currency": "EUR",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "language": "de",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    },
  • "offer_number": "AN-2026-0001",
  • "valid_until": "2019-08-24",
  • "supersedes": {
    },
  • "accepted_at": 0,
  • "rejected_at": 0
}

Partially update offer fields and/or status

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null
Reference (object) or null

Re-pick the issuing Company. Validated against the tenant's per-doc-type allowed list. Only editable while the offer is in draft. Per the no-bare-id rule the wire shape is the full Reference object.

Reference (object) or null

Re-pick the sales channel, or null to clear. Only editable while the offer is in draft.

issue_date
string <date>
currency
string = 3 characters
buyer_reference
string

EN 16931 BT-10. Left out of a PATCH that changes business_partner, it is taken from the new partner's identifiers, as on a create.

purchase_order_reference
string

EN 16931 BT-13. Left out of a PATCH that changes business_partner, the new partner's purchase_order_reference is taken.

contract_reference
string
project_reference
string
subject
string or null
object (InvoicePeriod)

Invoice-level invoicing period (EN 16931 BG-14).

buyer_name
string
buyer_legal_registration_id
string
buyer_identifier
string
buyer_identifier_scheme_id
string or null

EN 16931 BT-46-1 — ISO/IEC 6523 scheme of buyer_identifier.

buyer_customer_number
string or null
buyer_vat_id
string
buyer_vat_id_type
string

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb).

object (InvoicePartyContact)

Contact group (EN 16931 BG-6 / BG-9).

object (InvoiceElectronicAddress)

EN 16931 BT-49. Left out of a PATCH that changes business_partner, the new partner's is taken.

object (InvoicePayee)

Third-party payee (EN 16931 BG-10). Populated only when the party receiving payment differs from the seller (e.g. factoring).

payment_terms_text
string
InvoicePaymentTerms (object) or null
remittance_information
string
Array of objects (InvoiceLineItemCreate)

The offer's positions. credited_line_item is for credit notes only; an offer refuses it with billing_document.credited_line_item_on_credit_note_only.

notes
Array of strings or null

Replaces the persisted list. null / omitted = no change; [] clears the field.

status
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"

Moving to finalized stamps the offer number and asks for the PDF, which is rendered in the background — poll /offers/{offer_id}/documents for it. sent only records that the finalized offer went out; a finalized offer may also be answered without it. A rejected offer may go back to sent — reopening keeps the number and the document. expired and superseded are terminal.

show_gross_values_per_line_item
boolean

Whether each line shows its value with VAT included (true) or net of VAT (false). Omitted on create, the offer takes the default_show_gross_values_per_line_item of its offer type. Draft only; changing it recalculates the lines from their prices as entered and never changes a price.

type_id
string or null
schema_version
string or null
object
object or null

The slots sent replace the whole address map, each stored in full with any part left out as null. addresses: null is ignored.

valid_until
string <date>

Last day the quoted price stands. Defaults to issue_date + the tenant's offer.default_validity_days.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the offer number, or id while still a draft).

required
object

self is the offer's own resource URL. Its documents live under /resource/v1/offers/{id}/documents. Further rels may be present; a client follows the ones it knows.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "sent" "accepted" "rejected" "expired" "superseded"
issue_date
required
string <date>
currency
required
string
required
Array of objects (OfferLineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the offer's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112.

required
Array of objects (InvoiceVatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed from the lines; read-only on the API. The renderer prints it as stored.

show_gross_values_per_line_item
required
boolean

Whether each line shows its value with VAT included. When true, every line carries line_total_gross and payable_amount is the sum of the line grosses.

required
object (MonetaryAmount)

EN 16931 BT-114. On an offer showing gross values, the sum of the line grosses less tax_inclusive; 0.00 otherwise. Stored, also when zero.

required
object (MonetaryAmount)

EN 16931 BT-115 = tax_inclusive + rounding_amount; an offer has no prepaid amount.

language
required
string

The language the offer is written in. Snapshotted from the business partner when the draft is created, refreshed on every draft save and frozen once the offer leaves draft; falls back to the tenant's default language when the partner has none. Always present. Read-only: it is not accepted on input.

notes
required
Array of strings

EN 16931 BT-22 notes (0..n), printed on the offer.

type_id
required
string

The tenant type this offer was created under.

required
object
required
object

Snapshotted address per slot the offer type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

offer_number
required
string

Empty ("") until the offer is finalized. Offer numbers are not gap-free.

valid_until
required
string or null <date>
required
Reference (object) or null

The offer this one replaces, when it is a revision.

accepted_at
required
integer or null

Unix seconds.

rejected_at
required
integer or null

Unix seconds.

required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...), stored on the record itself.

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this offer, null if none.

InvoicePaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2019-08-24",
  • "currency": "str",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "subject": "string",
  • "invoicing_period": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_identifier_scheme_id": "string",
  • "buyer_customer_number": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [
    ],
  • "status": "draft",
  • "show_gross_values_per_line_item": true,
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    },
  • "valid_until": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "identifiers": [
    ],
  • "_id": "off_a1b2c3d4e5f6",
  • "_class": "offer",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "currency": "EUR",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "rounding_amount": {
    },
  • "payable_amount": {
    },
  • "language": "de",
  • "vat_breakdown": [
    ],
  • "show_gross_values_per_line_item": true,
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "type_id": "string",
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    },
  • "offer_number": "AN-2026-0001",
  • "valid_until": "2019-08-24",
  • "supersedes": {
    },
  • "accepted_at": 0,
  • "rejected_at": 0
}

Delete a draft offer

Only a draft. A finalized offer is a document the customer holds — reject it or let it expire, which keeps the record of what was quoted.

Authorizations:
BearerAuth
path Parameters
offer_id
required
string
Example: off_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Bills

List bills received from suppliers

Bills are invoices the tenant received from suppliers. An invoice the tenant issues is under /resource/v1/invoices. With no filter, search term or sort, the list is read from the database, newest first, and is exact. Any of q, supplier_invoice_number, status, payment_status, outstanding, has_warnings, due_date_from, due_date_to or sort answers from the bill search index instead, which is eventually consistent: a bill changed a moment ago can be listed as it was, or not yet. A next_token from one kind of list is not accepted by the other, and an index next_token only continues the order it was issued under: the same sort, and for a search term sorted by relevance the same q. Any other is a 422. Every item carries its bill-local warnings only (scope: local); the cross-row ones come with a single bill.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

bill_number
string

Only the bill carrying this number of ours, ignoring letter case and surrounding whitespace. Answered from a lookup row, in one page with a null next_token, and every other filter is ignored.

q
string

Matches our number, the supplier's number and the supplier's name.

supplier_invoice_number
string

Only bills carrying this number printed on the supplier's invoice, not Raccoon's bill_number. Matched whole, ignoring letter case, accents and surrounding whitespace.

status
string^(received|under_review|approved|rejected)(,(...

Only bills in one of these statuses, comma-separated, e.g. received,under_review.

payment_status
string^(unpaid|partially_paid|paid)(,(unpaid|partia...

Only bills with one of these payment statuses, comma-separated.

outstanding
string
Enum: "true" "false"

true: only bills still to pay — not rejected, not a 381 credit note, and with an amount due above zero. false: only the others.

has_warnings
string
Enum: "true" "false"

true: only bills raising a bill-local warning. false: only bills raising none.

due_date_from
string <date>

Only bills due on or after this day.

due_date_to
string <date>

Only bills due on or before this day.

sort
string
Enum: "newest" "due_date"

newest (default; best match first when q is given) or due_date, earliest first with undated bills last.

Responses

Response Schema: application/json
required
Array of objects (BillResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Record a bill received from a supplier

Records an invoice the tenant received from a supplier, as the document states it. Every field is optional; a bill with no lines and no VAT breakdown is valid. The server assigns our bill_number from the bill numbering series (seeded on first use as ER-{YEAR}-{ID:4} for German-speaking tenants, BILL-{YEAR}-{ID:4} otherwise). When no buyer party is sent, the tenant's default company is added as the buyer. The supplier's file can come in the same call, in one of two ways. original_file_upload describes a file still to upload: the bill and its bill.original file row are created, and upload in the response says where to POST the bytes. source_file names a chat attachment already uploaded, which is copied onto the bill as its original (the attachment itself is left as it is). The file is checked first — PDF, JPEG, PNG, WebP or XML, at most 20 MB, HEIC refused — so a refused file creates no bill. payment records a bill that was paid on the spot (M-Pesa, cash) in the same request: the bill is written, then paid with a new outgoing payment. The payment is checked before anything is written (the bill_payment.* rejections of POST /bills/{bill_id}/payments). A retry with the same payment.dedupe_key returns the bill already recorded, with upload null, and finishes its payment if the first attempt did not. Each plan includes a number of bills per billing period (max_bills_per_month). Past it the create answers 402 plan_limit_reached with metric bills_created before anything is written; a retry with the same payment.dedupe_key is not counted again. Deleting a bill does not give the count back.

Authorizations:
BearerAuth
Request Body schema: application/json
required
BillOriginalUpload (object) or null

The supplier's file, to upload to the upload form the response returns.

ReferenceValue (object) or null

A chat attachment (chat_session.attachment) to copy onto the bill as its original.

BillCapturePayment (object) or null

A payment made on the spot, recorded with the bill in the same request.

supplier_invoice_number
string or null <= 200 characters

The supplier's own invoice number (BT-1). Never a key: two suppliers may use the same number.

issue_date
string or null <date>

BT-2.

type_code
string
Enum: "380" "381" "384" "389" "326" "875" "876" "877"

UNCL 1001 (BT-3, codelist un/cl_1001_bill). A 381 credit note carries positive amounts; the sign is the type. Defaults to 380.

currency
string or null = 3 characters

ISO 4217 (BT-5).

tax_currency
string or null = 3 characters

ISO 4217 (BT-6), when VAT is also stated in another currency.

tax_point_date
string or null <date>

BT-7. Exclusive with tax_point_code.

tax_point_code
string or null
Enum: "3" "35" "432" null

UNCL 2005 (BT-8). Exclusive with tax_point_date.

due_date
string or null <date>

BT-9.

buyer_reference
string or null

BT-10.

project_reference
string or null

BT-11.

contract_reference
string or null

BT-12.

purchase_order_reference
string or null

BT-13, verbatim text.

InvoicePeriod (object) or null

BG-14.

InvoiceBillingReference (object) or null

BG-3.

notes
Array of strings

BT-22.

payment_terms_text
string or null

BT-20.

payment_means_code
string or null <= 3 characters

UNCL 4461 (BT-81).

remittance_information
string or null

BT-83.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-106 as stated. Every total is optional: null means the document does not state it, never zero.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-107.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-108.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-109.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-110.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-111, in tax_currency.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-112.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-113.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-114.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-115.

BillPaymentInstructions (object) or null
BillSupplierClearance (object) or null
Array of objects (BillParty)

At most one per role. When the create names no buyer, the tenant's default company is added as the buyer.

Array of objects (BillLineItemInput) <= 500 items
Array of objects (BillAllowanceCharge)

Document-level allowances and charges.

Array of objects (BillVatBreakdownLine)

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Our bill number, else the supplier's number, else the id.

required
object
created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
ReferenceValue (object) or null
bill_number
required
string

Our number for the bill, from the bill numbering series (ER-2026-0001 / BILL-2026-0001). Not gap-free.

status
required
string
Enum: "received" "under_review" "approved" "rejected"

Review status. Starts received.

rejection_reason
required
string or null
approved_at
required
integer or null
required
ReferenceValue (object) or null
first_approved_at
required
integer or null

When the bill was first approved. Set once and never cleared by a reopen, so a bill that has ever been approved can no longer be deleted or have its original replaced.

capture_source
required
string
Enum: "manual" "extraction" "embedded_xml"

How the figures got onto the bill.

required
BillExtraction (object) or null
required
ReferenceValue (object) or null

The supplier's file as received.

version
required
integer >= 1

Bumped on every write. Send it back on PATCH.

supplier_invoice_number
required
string or null <= 200 characters

The supplier's own invoice number (BT-1). Never a key: two suppliers may use the same number.

issue_date
required
string or null <date>

BT-2.

type_code
required
string
Enum: "380" "381" "384" "389" "326" "875" "876" "877"

UNCL 1001 (BT-3, codelist un/cl_1001_bill). A 381 credit note carries positive amounts; the sign is the type. Defaults to 380.

currency
required
string or null = 3 characters

ISO 4217 (BT-5).

tax_currency
required
string or null = 3 characters

ISO 4217 (BT-6), when VAT is also stated in another currency.

tax_point_date
required
string or null <date>

BT-7. Exclusive with tax_point_code.

tax_point_code
required
string or null
Enum: "3" "35" "432" null

UNCL 2005 (BT-8). Exclusive with tax_point_date.

due_date
required
string or null <date>

BT-9.

buyer_reference
required
string or null

BT-10.

project_reference
required
string or null

BT-11.

contract_reference
required
string or null

BT-12.

purchase_order_reference
required
string or null

BT-13, verbatim text.

required
InvoicePeriod (object) or null

BG-14.

required
InvoiceBillingReference (object) or null

BG-3.

notes
required
Array of strings

BT-22.

payment_terms_text
required
string or null

BT-20.

payment_means_code
required
string or null <= 3 characters

UNCL 4461 (BT-81).

remittance_information
required
string or null

BT-83.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-106 as stated. Every total is optional: null means the document does not state it, never zero.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-107.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-108.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-109.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-110.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-111, in tax_currency.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-112.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-113.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-114.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-115.

required
BillPaymentInstructionsResponse (object) or null
required
BillSupplierClearanceResponse (object) or null
required
Array of objects (BillPartyResponse)
required
Array of objects (BillLineItemResponse)
required
Array of objects (BillAllowanceChargeResponse)
required
Array of objects (BillVatBreakdownLineResponse)
payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

Payment axis, separate from status. Recomputed from the caches; a PATCH that changes payable_amount re-derives it.

required
number or string (Decimal)
required
number or string (Decimal)
required
(Decimal (Decimal (number) or Decimal (string))) or null

payable_amount less amount_paid and amount_written_off. Computed, never stored; null when the bill states no payable amount.

allocation_version
required
integer
required
Array of objects (BillWarning)

Where the figures do not add up or something is missing. Computed on every read, never stored, never blocking. Empty when there is nothing to report. A list returns only the local ones.

outstanding
required
boolean

The bill still asks to be paid and counts in what the tenant owes: not rejected, not a 381 credit note, and amount_due above zero. The same rule as the list's outstanding filter and the summary.

required
PresignedPost (object) or null

The presigned upload form for original_file_upload; null otherwise.

Request samples

Content type
application/json
{
  • "original_file_upload": {
    },
  • "source_file": {
    },
  • "payment": {
    },
  • "supplier_invoice_number": "string",
  • "issue_date": "2019-08-24",
  • "type_code": "380",
  • "currency": "str",
  • "tax_currency": "str",
  • "tax_point_date": "2019-08-24",
  • "tax_point_code": "3",
  • "due_date": "2019-08-24",
  • "buyer_reference": "string",
  • "project_reference": "string",
  • "contract_reference": "string",
  • "purchase_order_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "notes": [
    ],
  • "payment_terms_text": "string",
  • "payment_means_code": "str",
  • "remittance_information": "string",
  • "line_net_total": -999999999999,
  • "allowance_total": -999999999999,
  • "charge_total": -999999999999,
  • "tax_exclusive_amount": -999999999999,
  • "tax_total": -999999999999,
  • "tax_total_in_tax_currency": -999999999999,
  • "tax_inclusive_amount": -999999999999,
  • "prepaid_amount": -999999999999,
  • "rounding_amount": -999999999999,
  • "payable_amount": -999999999999,
  • "payment_instructions": {
    },
  • "supplier_clearance": {
    },
  • "parties": [
    ],
  • "line_items": [
    ],
  • "allowances_charges": [
    ],
  • "vat_breakdown": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "bill_a1b2c3d4e5f6",
  • "_class": "bill",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "tenant": {
    },
  • "bill_number": "BILL-2026-0001",
  • "status": "received",
  • "rejection_reason": "string",
  • "approved_at": 0,
  • "approved_by": {
    },
  • "first_approved_at": 0,
  • "capture_source": "manual",
  • "extraction": {
    },
  • "original_file": {
    },
  • "version": 1,
  • "supplier_invoice_number": "string",
  • "issue_date": "2019-08-24",
  • "type_code": "380",
  • "currency": "str",
  • "tax_currency": "str",
  • "tax_point_date": "2019-08-24",
  • "tax_point_code": "3",
  • "due_date": "2019-08-24",
  • "buyer_reference": "string",
  • "project_reference": "string",
  • "contract_reference": "string",
  • "purchase_order_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "notes": [
    ],
  • "payment_terms_text": "string",
  • "payment_means_code": "str",
  • "remittance_information": "string",
  • "line_net_total": -999999999999,
  • "allowance_total": -999999999999,
  • "charge_total": -999999999999,
  • "tax_exclusive_amount": -999999999999,
  • "tax_total": -999999999999,
  • "tax_total_in_tax_currency": -999999999999,
  • "tax_inclusive_amount": -999999999999,
  • "prepaid_amount": -999999999999,
  • "rounding_amount": -999999999999,
  • "payable_amount": -999999999999,
  • "payment_instructions": {
    },
  • "supplier_clearance": {
    },
  • "parties": [
    ],
  • "line_items": [
    ],
  • "allowances_charges": [
    ],
  • "vat_breakdown": [
    ],
  • "payment_status": "unpaid",
  • "amount_paid": 0,
  • "amount_written_off": 0,
  • "amount_due": 0,
  • "allocation_version": 0,
  • "warnings": [
    ],
  • "outstanding": true,
  • "upload": {
    }
}

What the tenant owes on bills, per currency

Sums of amount_due over the outstanding bills — all of them, the overdue ones and the ones due in the next seven days — per currency. A 381 credit note and a rejected bill are never counted. Read from the bill search index, so it is eventually consistent.

Authorizations:
BearerAuth
query Parameters
as_of
string <date>

The day to count from, normally the caller's today. Defaults to today in UTC.

Responses

Response Schema: application/json
as_of
required
string <date>

The day the figures are counted from.

due_this_week_until
required
string <date>

The last day due_this_week covers, six days after as_of.

required
Array of objects (BillTotal)

Every outstanding bill, per currency, ordered by currency.

required
Array of objects (BillTotal)

The outstanding bills due before as_of.

required
Array of objects (BillTotal)

The outstanding bills due from as_of to due_this_week_until.

Response samples

Content type
application/json
{
  • "as_of": "2019-08-24",
  • "due_this_week_until": "2019-08-24",
  • "to_pay": [
    ],
  • "overdue": [
    ],
  • "due_this_week": [
    ]
}

Get a bill received from a supplier

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Our bill number, else the supplier's number, else the id.

required
object
created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
ReferenceValue (object) or null
bill_number
required
string

Our number for the bill, from the bill numbering series (ER-2026-0001 / BILL-2026-0001). Not gap-free.

status
required
string
Enum: "received" "under_review" "approved" "rejected"

Review status. Starts received.

rejection_reason
required
string or null
approved_at
required
integer or null
required
ReferenceValue (object) or null
first_approved_at
required
integer or null

When the bill was first approved. Set once and never cleared by a reopen, so a bill that has ever been approved can no longer be deleted or have its original replaced.

capture_source
required
string
Enum: "manual" "extraction" "embedded_xml"

How the figures got onto the bill.

required
BillExtraction (object) or null
required
ReferenceValue (object) or null

The supplier's file as received.

version
required
integer >= 1

Bumped on every write. Send it back on PATCH.

supplier_invoice_number
required
string or null <= 200 characters

The supplier's own invoice number (BT-1). Never a key: two suppliers may use the same number.

issue_date
required
string or null <date>

BT-2.

type_code
required
string
Enum: "380" "381" "384" "389" "326" "875" "876" "877"

UNCL 1001 (BT-3, codelist un/cl_1001_bill). A 381 credit note carries positive amounts; the sign is the type. Defaults to 380.

currency
required
string or null = 3 characters

ISO 4217 (BT-5).

tax_currency
required
string or null = 3 characters

ISO 4217 (BT-6), when VAT is also stated in another currency.

tax_point_date
required
string or null <date>

BT-7. Exclusive with tax_point_code.

tax_point_code
required
string or null
Enum: "3" "35" "432" null

UNCL 2005 (BT-8). Exclusive with tax_point_date.

due_date
required
string or null <date>

BT-9.

buyer_reference
required
string or null

BT-10.

project_reference
required
string or null

BT-11.

contract_reference
required
string or null

BT-12.

purchase_order_reference
required
string or null

BT-13, verbatim text.

required
InvoicePeriod (object) or null

BG-14.

required
InvoiceBillingReference (object) or null

BG-3.

notes
required
Array of strings

BT-22.

payment_terms_text
required
string or null

BT-20.

payment_means_code
required
string or null <= 3 characters

UNCL 4461 (BT-81).

remittance_information
required
string or null

BT-83.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-106 as stated. Every total is optional: null means the document does not state it, never zero.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-107.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-108.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-109.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-110.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-111, in tax_currency.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-112.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-113.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-114.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-115.

required
BillPaymentInstructionsResponse (object) or null
required
BillSupplierClearanceResponse (object) or null
required
Array of objects (BillPartyResponse)
required
Array of objects (BillLineItemResponse)
required
Array of objects (BillAllowanceChargeResponse)
required
Array of objects (BillVatBreakdownLineResponse)
payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

Payment axis, separate from status. Recomputed from the caches; a PATCH that changes payable_amount re-derives it.

required
number or string (Decimal)
required
number or string (Decimal)
required
(Decimal (Decimal (number) or Decimal (string))) or null

payable_amount less amount_paid and amount_written_off. Computed, never stored; null when the bill states no payable amount.

allocation_version
required
integer
required
Array of objects (BillWarning)

Where the figures do not add up or something is missing. Computed on every read, never stored, never blocking. Empty when there is nothing to report. A list returns only the local ones.

outstanding
required
boolean

The bill still asks to be paid and counts in what the tenant owes: not rejected, not a 381 credit note, and amount_due above zero. The same rule as the list's outstanding filter and the summary.

Response samples

Content type
application/json
{
  • "_id": "bill_a1b2c3d4e5f6",
  • "_class": "bill",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "tenant": {
    },
  • "bill_number": "BILL-2026-0001",
  • "status": "received",
  • "rejection_reason": "string",
  • "approved_at": 0,
  • "approved_by": {
    },
  • "first_approved_at": 0,
  • "capture_source": "manual",
  • "extraction": {
    },
  • "original_file": {
    },
  • "version": 1,
  • "supplier_invoice_number": "string",
  • "issue_date": "2019-08-24",
  • "type_code": "380",
  • "currency": "str",
  • "tax_currency": "str",
  • "tax_point_date": "2019-08-24",
  • "tax_point_code": "3",
  • "due_date": "2019-08-24",
  • "buyer_reference": "string",
  • "project_reference": "string",
  • "contract_reference": "string",
  • "purchase_order_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "notes": [
    ],
  • "payment_terms_text": "string",
  • "payment_means_code": "str",
  • "remittance_information": "string",
  • "line_net_total": -999999999999,
  • "allowance_total": -999999999999,
  • "charge_total": -999999999999,
  • "tax_exclusive_amount": -999999999999,
  • "tax_total": -999999999999,
  • "tax_total_in_tax_currency": -999999999999,
  • "tax_inclusive_amount": -999999999999,
  • "prepaid_amount": -999999999999,
  • "rounding_amount": -999999999999,
  • "payable_amount": -999999999999,
  • "payment_instructions": {
    },
  • "supplier_clearance": {
    },
  • "parties": [
    ],
  • "line_items": [
    ],
  • "allowances_charges": [
    ],
  • "vat_breakdown": [
    ],
  • "payment_status": "unpaid",
  • "amount_paid": 0,
  • "amount_written_off": 0,
  • "amount_due": 0,
  • "allocation_version": 0,
  • "warnings": [
    ],
  • "outstanding": true
}

Change a bill received from a supplier

A whole-document write: send the fields to change, lists replaced whole, plus the version last read (in the body or as If-Match). A stale version is refused with 409 and nothing is written. Lines keep their _id when it is sent back. Sending status moves the bill along its review (see BillUpdate.status); approving is refused for the agent (403).

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6
header Parameters
If-Match
string

The bill's version as last read (e.g. 3 or "3"). Required unless the body carries version; when both are sent they must agree.

Request Body schema: application/json
required
version
integer >= 1
status
string
Enum: "received" "under_review" "approved" "rejected"

The review status. Allowed moves: received to under_review, approved or rejected; under_review to approved, rejected or received; rejected to received; approved to under_review (reopen, which clears approved_at and approved_by but keeps first_approved_at). Any other move is 422. Approving needs a seller name, a buyer, currency, issue_date and payable_amount on the resulting bill (422 naming the missing ones) and is refused for the agent (403). Rejecting needs rejection_reason and no payments (409). An approved bill refuses changes other than notes and line product (409). Approving or rejecting while extraction.status is running is 409 bill.extraction_running; while it is proposed it is 422 bill.extraction_proposed, unless the same write settles the reading with extraction.

rejection_reason
string or null <= 2000 characters

Why the bill is rejected. Required when rejecting; refused on a bill that is not rejected. Cleared when a rejected bill goes back to received.

acknowledged_warnings
Array of strings
Items Value: "bill.warning.payee_account_changed"

Read by this write only, never stored. Approving while the bill.warning.payee_account_changed warning is live needs it listed here, else 422.

object

Settles the extraction's proposal in the same write as the values kept from it. Only a proposed extraction can be settled (409 otherwise). applied marks the bill capture_source extraction; both drop the proposal and keep the levels.

supplier_invoice_number
string or null <= 200 characters

The supplier's own invoice number (BT-1). Never a key: two suppliers may use the same number.

issue_date
string or null <date>

BT-2.

type_code
string
Enum: "380" "381" "384" "389" "326" "875" "876" "877"

UNCL 1001 (BT-3, codelist un/cl_1001_bill). A 381 credit note carries positive amounts; the sign is the type. Defaults to 380.

currency
string or null = 3 characters

ISO 4217 (BT-5).

tax_currency
string or null = 3 characters

ISO 4217 (BT-6), when VAT is also stated in another currency.

tax_point_date
string or null <date>

BT-7. Exclusive with tax_point_code.

tax_point_code
string or null
Enum: "3" "35" "432" null

UNCL 2005 (BT-8). Exclusive with tax_point_date.

due_date
string or null <date>

BT-9.

buyer_reference
string or null

BT-10.

project_reference
string or null

BT-11.

contract_reference
string or null

BT-12.

purchase_order_reference
string or null

BT-13, verbatim text.

InvoicePeriod (object) or null

BG-14.

InvoiceBillingReference (object) or null

BG-3.

notes
Array of strings

BT-22.

payment_terms_text
string or null

BT-20.

payment_means_code
string or null <= 3 characters

UNCL 4461 (BT-81).

remittance_information
string or null

BT-83.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-106 as stated. Every total is optional: null means the document does not state it, never zero.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-107.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-108.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-109.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-110.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-111, in tax_currency.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-112.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-113.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-114.

(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-115.

BillPaymentInstructions (object) or null
BillSupplierClearance (object) or null
Array of objects (BillParty)

At most one per role. When the create names no buyer, the tenant's default company is added as the buyer.

Array of objects (BillLineItemInput) <= 500 items
Array of objects (BillAllowanceCharge)

Document-level allowances and charges.

Array of objects (BillVatBreakdownLine)

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Our bill number, else the supplier's number, else the id.

required
object
created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
ReferenceValue (object) or null
bill_number
required
string

Our number for the bill, from the bill numbering series (ER-2026-0001 / BILL-2026-0001). Not gap-free.

status
required
string
Enum: "received" "under_review" "approved" "rejected"

Review status. Starts received.

rejection_reason
required
string or null
approved_at
required
integer or null
required
ReferenceValue (object) or null
first_approved_at
required
integer or null

When the bill was first approved. Set once and never cleared by a reopen, so a bill that has ever been approved can no longer be deleted or have its original replaced.

capture_source
required
string
Enum: "manual" "extraction" "embedded_xml"

How the figures got onto the bill.

required
BillExtraction (object) or null
required
ReferenceValue (object) or null

The supplier's file as received.

version
required
integer >= 1

Bumped on every write. Send it back on PATCH.

supplier_invoice_number
required
string or null <= 200 characters

The supplier's own invoice number (BT-1). Never a key: two suppliers may use the same number.

issue_date
required
string or null <date>

BT-2.

type_code
required
string
Enum: "380" "381" "384" "389" "326" "875" "876" "877"

UNCL 1001 (BT-3, codelist un/cl_1001_bill). A 381 credit note carries positive amounts; the sign is the type. Defaults to 380.

currency
required
string or null = 3 characters

ISO 4217 (BT-5).

tax_currency
required
string or null = 3 characters

ISO 4217 (BT-6), when VAT is also stated in another currency.

tax_point_date
required
string or null <date>

BT-7. Exclusive with tax_point_code.

tax_point_code
required
string or null
Enum: "3" "35" "432" null

UNCL 2005 (BT-8). Exclusive with tax_point_date.

due_date
required
string or null <date>

BT-9.

buyer_reference
required
string or null

BT-10.

project_reference
required
string or null

BT-11.

contract_reference
required
string or null

BT-12.

purchase_order_reference
required
string or null

BT-13, verbatim text.

required
InvoicePeriod (object) or null

BG-14.

required
InvoiceBillingReference (object) or null

BG-3.

notes
required
Array of strings

BT-22.

payment_terms_text
required
string or null

BT-20.

payment_means_code
required
string or null <= 3 characters

UNCL 4461 (BT-81).

remittance_information
required
string or null

BT-83.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-106 as stated. Every total is optional: null means the document does not state it, never zero.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-107.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-108.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-109.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-110.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-111, in tax_currency.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-112.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-113.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-114.

required
(BillDecimal (BillDecimal (number) or BillDecimal (string))) or null

BT-115.

required
BillPaymentInstructionsResponse (object) or null
required
BillSupplierClearanceResponse (object) or null
required
Array of objects (BillPartyResponse)
required
Array of objects (BillLineItemResponse)
required
Array of objects (BillAllowanceChargeResponse)
required
Array of objects (BillVatBreakdownLineResponse)
payment_status
required
string
Enum: "unpaid" "partially_paid" "paid"

Payment axis, separate from status. Recomputed from the caches; a PATCH that changes payable_amount re-derives it.

required
number or string (Decimal)
required
number or string (Decimal)
required
(Decimal (Decimal (number) or Decimal (string))) or null

payable_amount less amount_paid and amount_written_off. Computed, never stored; null when the bill states no payable amount.

allocation_version
required
integer
required
Array of objects (BillWarning)

Where the figures do not add up or something is missing. Computed on every read, never stored, never blocking. Empty when there is nothing to report. A list returns only the local ones.

outstanding
required
boolean

The bill still asks to be paid and counts in what the tenant owes: not rejected, not a 381 credit note, and amount_due above zero. The same rule as the list's outstanding filter and the summary.

Request samples

Content type
application/json
{
  • "version": 1,
  • "status": "received",
  • "rejection_reason": "string",
  • "acknowledged_warnings": [
    ],
  • "extraction": {
    },
  • "supplier_invoice_number": "string",
  • "issue_date": "2019-08-24",
  • "type_code": "380",
  • "currency": "str",
  • "tax_currency": "str",
  • "tax_point_date": "2019-08-24",
  • "tax_point_code": "3",
  • "due_date": "2019-08-24",
  • "buyer_reference": "string",
  • "project_reference": "string",
  • "contract_reference": "string",
  • "purchase_order_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "notes": [
    ],
  • "payment_terms_text": "string",
  • "payment_means_code": "str",
  • "remittance_information": "string",
  • "line_net_total": -999999999999,
  • "allowance_total": -999999999999,
  • "charge_total": -999999999999,
  • "tax_exclusive_amount": -999999999999,
  • "tax_total": -999999999999,
  • "tax_total_in_tax_currency": -999999999999,
  • "tax_inclusive_amount": -999999999999,
  • "prepaid_amount": -999999999999,
  • "rounding_amount": -999999999999,
  • "payable_amount": -999999999999,
  • "payment_instructions": {
    },
  • "supplier_clearance": {
    },
  • "parties": [
    ],
  • "line_items": [
    ],
  • "allowances_charges": [
    ],
  • "vat_breakdown": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "bill_a1b2c3d4e5f6",
  • "_class": "bill",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "tenant": {
    },
  • "bill_number": "BILL-2026-0001",
  • "status": "received",
  • "rejection_reason": "string",
  • "approved_at": 0,
  • "approved_by": {
    },
  • "first_approved_at": 0,
  • "capture_source": "manual",
  • "extraction": {
    },
  • "original_file": {
    },
  • "version": 1,
  • "supplier_invoice_number": "string",
  • "issue_date": "2019-08-24",
  • "type_code": "380",
  • "currency": "str",
  • "tax_currency": "str",
  • "tax_point_date": "2019-08-24",
  • "tax_point_code": "3",
  • "due_date": "2019-08-24",
  • "buyer_reference": "string",
  • "project_reference": "string",
  • "contract_reference": "string",
  • "purchase_order_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "notes": [
    ],
  • "payment_terms_text": "string",
  • "payment_means_code": "str",
  • "remittance_information": "string",
  • "line_net_total": -999999999999,
  • "allowance_total": -999999999999,
  • "charge_total": -999999999999,
  • "tax_exclusive_amount": -999999999999,
  • "tax_total": -999999999999,
  • "tax_total_in_tax_currency": -999999999999,
  • "tax_inclusive_amount": -999999999999,
  • "prepaid_amount": -999999999999,
  • "rounding_amount": -999999999999,
  • "payable_amount": -999999999999,
  • "payment_instructions": {
    },
  • "supplier_clearance": {
    },
  • "parties": [
    ],
  • "line_items": [
    ],
  • "allowances_charges": [
    ],
  • "vat_breakdown": [
    ],
  • "payment_status": "unpaid",
  • "amount_paid": 0,
  • "amount_written_off": 0,
  • "amount_due": 0,
  • "allocation_version": 0,
  • "warnings": [
    ],
  • "outstanding": true
}

Delete a bill recorded by mistake

Deletes the bill, its original file and its number lookups. Only a bill still received, never approved and with no payment booked against it can be deleted; anything else is 409 and is rejected instead. Our bill number is not handed out again.

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Read a bill received from a supplier off its original file

Starts one reading of the bill's original (a photo, a PDF, or an e-invoice XML; a PDF's embedded ZUGFeRD / Factur-X XML is read as the authoritative input) and answers 202 with the bill, its extraction running. The reading happens off the request path; follow the bill (GET /bills/{bill_id}) until extraction.status is proposed or failed. The reading is a proposal: nothing on the bill changes until a PATCH carries extraction: {"status": "applied"}. One reading counts as one agent action. Refused with 422 when the bill has no original, 409 while its original is still uploading, while a reading runs or once the bill is approved or rejected, and 402 when the plan has no agent action left.

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "_id": "bill_a1b2c3d4e5f6",
  • "_class": "bill",
  • "_name": "Acme Corp",
  • "_links": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "tenant": {
    },
  • "bill_number": "BILL-2026-0001",
  • "status": "received",
  • "rejection_reason": "string",
  • "approved_at": 0,
  • "approved_by": {
    },
  • "first_approved_at": 0,
  • "capture_source": "manual",
  • "extraction": {
    },
  • "original_file": {
    },
  • "version": 1,
  • "supplier_invoice_number": "string",
  • "issue_date": "2019-08-24",
  • "type_code": "380",
  • "currency": "str",
  • "tax_currency": "str",
  • "tax_point_date": "2019-08-24",
  • "tax_point_code": "3",
  • "due_date": "2019-08-24",
  • "buyer_reference": "string",
  • "project_reference": "string",
  • "contract_reference": "string",
  • "purchase_order_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "notes": [
    ],
  • "payment_terms_text": "string",
  • "payment_means_code": "str",
  • "remittance_information": "string",
  • "line_net_total": -999999999999,
  • "allowance_total": -999999999999,
  • "charge_total": -999999999999,
  • "tax_exclusive_amount": -999999999999,
  • "tax_total": -999999999999,
  • "tax_total_in_tax_currency": -999999999999,
  • "tax_inclusive_amount": -999999999999,
  • "prepaid_amount": -999999999999,
  • "rounding_amount": -999999999999,
  • "payable_amount": -999999999999,
  • "payment_instructions": {
    },
  • "supplier_clearance": {
    },
  • "parties": [
    ],
  • "line_items": [
    ],
  • "allowances_charges": [
    ],
  • "vat_breakdown": [
    ],
  • "payment_status": "unpaid",
  • "amount_paid": 0,
  • "amount_written_off": 0,
  • "amount_due": 0,
  • "allocation_version": 0,
  • "warnings": [
    ],
  • "outstanding": true
}

List the payments made on a bill received from a supplier

Voided allocations are included, as history.

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (BillPaymentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Record a payment made on a bill received from a supplier

Applies an outgoing payment to the bill and updates the bill's payment_status, amount_paid and amount_written_off in the same transaction. Supply payment (an outgoing payment already recorded) or new_payment (recorded here, direction: outgoing). A payment is a fact, so it can be recorded on a received, under_review or approved bill. Tax the tenant withheld goes in deductions; it settles its share of the bill.

Rejections (422): bill_payment.payment_incoming, bill_payment.currency_mismatch, bill_payment.bill_currency_missing, bill_payment.bill_rejected, bill_payment.payable_amount_missing, bill_payment.bill_is_credit_note (a 381), bill_payment.exceeds_payment_remainder, bill_payment.exceeds_open_balance, bill_payment.nothing_to_allocate. Two requests spending the same payment at once: one succeeds, the other re-reads and is refused with exceeds_payment_remainder.

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6
Request Body schema: application/json
required
One of
required
Reference (object) or null

Reference to an existing outgoing payment. Mutually exclusive with new_payment.

object or null
object (MonetaryAmountInput)

Cash to apply. Omit to pay as much of the bill's amount_due as the payment's remainder covers. May not exceed either.

Array of objects (BillPaymentDeduction)

Parts of the bill settled without cash. A bill of 100,000 paid as 95,000 plus a 5,000 withholding_tax deduction is paid.

dedupe_key
string or null [ 1 .. 128 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The allocation already recorded is returned unchanged.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (MonetaryAmount)

The cash applied — what the supplier was actually paid.

amount_deducted
required
number

Sum of this allocation's deductions, in the bill's currency.

required
Array of objects (BillPaymentDeductionResponse)
is_voided
required
boolean

Voided allocations are kept, not deleted, and excluded from every balance.

voided_at
required
integer or null

Unix epoch seconds

void_reason
required
string or null
dedupe_key
required
string or null
bill_number
required
string

Our number of the bill when the money was applied.

version
required
integer >= 1

Goes up by one with every change to the deductions.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object
required
object (BillTotalsAfterAllocation)

The bill's figures as this write left them, so no caller needs a follow-up GET.

Request samples

Content type
application/json
{
  • "payment": {
    },
  • "new_payment": {
    },
  • "amount": {
    },
  • "deductions": [
    ],
  • "dedupe_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "bpay_a1b2c3d4e5f6",
  • "_class": "bill_payment",
  • "bill": {
    },
  • "payment": {
    },
  • "amount": {
    },
  • "amount_deducted": 0,
  • "deductions": [
    ],
  • "is_voided": true,
  • "voided_at": 0,
  • "void_reason": "string",
  • "dedupe_key": "string",
  • "bill_number": "string",
  • "version": 1,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    },
  • "bill_totals": {
    }
}

Get one payment made on a bill

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6
bill_payment_id
required
string
Example: bpay_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (MonetaryAmount)

The cash applied — what the supplier was actually paid.

amount_deducted
required
number

Sum of this allocation's deductions, in the bill's currency.

required
Array of objects (BillPaymentDeductionResponse)
is_voided
required
boolean

Voided allocations are kept, not deleted, and excluded from every balance.

voided_at
required
integer or null

Unix epoch seconds

void_reason
required
string or null
dedupe_key
required
string or null
bill_number
required
string

Our number of the bill when the money was applied.

version
required
integer >= 1

Goes up by one with every change to the deductions.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Response samples

Content type
application/json
{
  • "_id": "bpay_a1b2c3d4e5f6",
  • "_class": "bill_payment",
  • "bill": {
    },
  • "payment": {
    },
  • "amount": {
    },
  • "amount_deducted": 0,
  • "deductions": [
    ],
  • "is_voided": true,
  • "voided_at": 0,
  • "void_reason": "string",
  • "dedupe_key": "string",
  • "bill_number": "string",
  • "version": 1,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Record a withholding certificate or remittance on a bill payment

Changes only certificate_reference and remitted_at on the deductions, never an amount. 422 bill_payment.remitted_at_not_withholding on a deduction that is not withheld tax, bill_payment.deductions_count_mismatch when the list does not line up; 409 bill_payment.voided on a voided allocation, bill_payment.deductions_conflict when another change to the deductions landed between this request's read and its write.

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6
bill_payment_id
required
string
Example: bpay_a1b2c3d4e5f6
Request Body schema: application/json
required
required
Array of objects (BillPaymentDeductionUpdate)

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (MonetaryAmount)

The cash applied — what the supplier was actually paid.

amount_deducted
required
number

Sum of this allocation's deductions, in the bill's currency.

required
Array of objects (BillPaymentDeductionResponse)
is_voided
required
boolean

Voided allocations are kept, not deleted, and excluded from every balance.

voided_at
required
integer or null

Unix epoch seconds

void_reason
required
string or null
dedupe_key
required
string or null
bill_number
required
string

Our number of the bill when the money was applied.

version
required
integer >= 1

Goes up by one with every change to the deductions.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

Request samples

Content type
application/json
{
  • "deductions": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "bpay_a1b2c3d4e5f6",
  • "_class": "bill_payment",
  • "bill": {
    },
  • "payment": {
    },
  • "amount": {
    },
  • "amount_deducted": 0,
  • "deductions": [
    ],
  • "is_voided": true,
  • "voided_at": 0,
  • "void_reason": "string",
  • "dedupe_key": "string",
  • "bill_number": "string",
  • "version": 1,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Void a payment made on a bill

Soft-void: the row is kept and excluded from every balance. The bill's balance and the payment's allocated total walk back. Allowed whatever the bill's status.

Authorizations:
BearerAuth
path Parameters
bill_id
required
string
Example: bill_a1b2c3d4e5f6
bill_payment_id
required
string
Example: bpay_a1b2c3d4e5f6
Request Body schema: application/json
optional
void_reason
string or null

Why the allocation was reversed. Recorded on the audit trail.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (MonetaryAmount)

The cash applied — what the supplier was actually paid.

amount_deducted
required
number

Sum of this allocation's deductions, in the bill's currency.

required
Array of objects (BillPaymentDeductionResponse)
is_voided
required
boolean

Voided allocations are kept, not deleted, and excluded from every balance.

voided_at
required
integer or null

Unix epoch seconds

void_reason
required
string or null
dedupe_key
required
string or null
bill_number
required
string

Our number of the bill when the money was applied.

version
required
integer >= 1

Goes up by one with every change to the deductions.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object
required
object (BillTotalsAfterAllocation)

The bill's figures as this write left them, so no caller needs a follow-up GET.

Request samples

Content type
application/json
{
  • "void_reason": "string"
}

Response samples

Content type
application/json
{
  • "_id": "bpay_a1b2c3d4e5f6",
  • "_class": "bill_payment",
  • "bill": {
    },
  • "payment": {
    },
  • "amount": {
    },
  • "amount_deducted": 0,
  • "deductions": [
    ],
  • "is_voided": true,
  • "voided_at": 0,
  • "void_reason": "string",
  • "dedupe_key": "string",
  • "bill_number": "string",
  • "version": 1,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    },
  • "bill_totals": {
    }
}

Payments

List the payments allocated to an invoice

Voided allocations are included: they are kept as history and shown struck through, not filtered out.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (InvoicePaymentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Record a payment against an invoice

This is what marks an invoice paid — PATCH {status: "paid"} is rejected. Supply payment to apply an existing payment, or new_payment to record and allocate in one transaction. Where the customer withheld tax or took a discount, pass the shortfall in deductions and the invoice still settles.

A credit note (document_type_code 381) is settled the other way: by an outgoing payment, the refund, with no deductions.

Rejections: invoice_payment.invoice_not_finalized (draft), invoice_payment.invoice_cancelled, invoice_payment.currency_mismatch, invoice_payment.payment_outgoing (the payment was paid out, not received), invoice_payment.payment_incoming_to_credit_note (money received cannot settle a credit note), invoice_payment.deductions_on_refund, invoice_payment.exceeds_payment_remainder, invoice_payment.exceeds_open_balance — the excess deliberately stays unallocated on the payment as credit on account.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
One of
required
Reference (object) or null

Reference to an existing payment. Mutually exclusive with new_payment.

object or null
object (MonetaryAmountInput)

Cash to apply. Omit to settle as much of the open balance as the payment's remainder covers, which is what the record-payment dialog wants. May not exceed either the invoice's amount_due or the payment's amount_unallocated.

Array of objects (PaymentDeduction)

Parts of the invoice this payment deliberately did not cover. The invoice settles on amount + deductions, so a Kenyan invoice of 100,000 paid as 95,000 cash plus a 5,000 withholding_tax deduction reaches paid.

dedupe_key
string or null [ 1 .. 128 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The allocation already recorded is returned unchanged, and a new_payment it carries is not recorded again. Keys are shared across kinds of record, so a dedupe_key inside new_payment must differ from this one.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (MonetaryAmount)

The cash applied — what the bank actually credited.

amount_deducted
required
number

Sum of this allocation's deductions, as a bare number in the invoice's currency (the figure is only meaningful alongside amount).

required
Array of objects (PaymentDeduction)
is_voided
required
boolean

Voided allocations are kept, not deleted, so "who un-paid this invoice, and why" stays answerable. They are excluded from every balance and are shown struck through.

voided_at
required
integer or null

Unix epoch seconds

void_reason
required
string or null
dedupe_key
required
string or null
invoice_number
required
string

The invoice's number as it stood when the money was applied. It duplicates invoice._name on purpose: an invoice is numbered in the same transaction that finalizes it and a draft cannot be allocated, so the value is immutable by the time this row exists — and carrying it here lets a list of allocations render the number a tenant recognises without reading an invoice per row.

Empty on rows written before this field existed; those fall back to reading the invoice.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object
required
object (InvoiceTotalsAfterAllocation)

The invoice figures as recomputed by this write, echoed so no caller needs a follow-up GET — the record-payment dialog needs the new status and open balance the moment it closes.

Request samples

Content type
application/json
{
  • "payment": {
    },
  • "new_payment": {
    },
  • "amount": {
    },
  • "deductions": [
    ],
  • "dedupe_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "ipay_a1b2c3d4e5f6",
  • "_class": "invoice_payment",
  • "invoice": {
    },
  • "payment": {
    },
  • "amount": {
    },
  • "amount_deducted": 0,
  • "deductions": [
    ],
  • "is_voided": true,
  • "voided_at": 0,
  • "void_reason": "string",
  • "dedupe_key": "string",
  • "invoice_number": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    },
  • "invoice_totals": {
    }
}

Void an allocation

Soft-void: the row is kept and excluded from every balance, so the audit trail survives. The invoice's balance walks back and its status reopens to finalized or overdue as its due date dictates. Deliberately not blocked on a dunned invoice — the commonest reason to unallocate is a payment matched to the wrong invoice, which is exactly the one that stopped being chased.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
invoice_payment_id
required
string
Example: ipay_a1b2c3d4e5f6
Request Body schema: application/json
optional
void_reason
string or null

Why the allocation was reversed. Recorded on the audit trail.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (MonetaryAmount)

The cash applied — what the bank actually credited.

amount_deducted
required
number

Sum of this allocation's deductions, as a bare number in the invoice's currency (the figure is only meaningful alongside amount).

required
Array of objects (PaymentDeduction)
is_voided
required
boolean

Voided allocations are kept, not deleted, so "who un-paid this invoice, and why" stays answerable. They are excluded from every balance and are shown struck through.

voided_at
required
integer or null

Unix epoch seconds

void_reason
required
string or null
dedupe_key
required
string or null
invoice_number
required
string

The invoice's number as it stood when the money was applied. It duplicates invoice._name on purpose: an invoice is numbered in the same transaction that finalizes it and a draft cannot be allocated, so the value is immutable by the time this row exists — and carrying it here lets a list of allocations render the number a tenant recognises without reading an invoice per row.

Empty on rows written before this field existed; those fall back to reading the invoice.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object
required
object (InvoiceTotalsAfterAllocation)

The invoice figures as recomputed by this write, echoed so no caller needs a follow-up GET — the record-payment dialog needs the new status and open balance the moment it closes.

Request samples

Content type
application/json
{
  • "void_reason": "string"
}

Response samples

Content type
application/json
{
  • "_id": "ipay_a1b2c3d4e5f6",
  • "_class": "invoice_payment",
  • "invoice": {
    },
  • "payment": {
    },
  • "amount": {
    },
  • "amount_deducted": 0,
  • "deductions": [
    ],
  • "is_voided": true,
  • "voided_at": 0,
  • "void_reason": "string",
  • "dedupe_key": "string",
  • "invoice_number": "string",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    },
  • "invoice_totals": {
    }
}

List where a payment's money went

The payment's own view of its allocations, which is what the allocation screen needs. Voided rows are included. A received payment lists the invoices it settled (invoice_payment rows); a payment made lists the bills it paid (bill_payment rows).

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of InvoicePaymentResponse (object) or BillPaymentResponse (object)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Spread a payment across several invoices

Settles up to 50 invoices from one payment. Each row is its own transaction, applied in the order given, so the remainder is consumed top-down and one row's failure never rolls back the rows that succeeded.

Answers 200 even when some rows failed — results[] carries a per-row verdict with a machine-readable error_code, and allocated_count / failed_count say how the batch went. A 4xx over the whole request would deny allocations that really happened.

Request-level rejections (422): invoice_payment.no_allocations, invoice_payment.too_many_allocations, invoice_payment.payment_outgoing (the payment was paid out, not received).

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6
Request Body schema: application/json
required
required
Array of objects (BulkAllocationRow) [ 1 .. 50 ] items

Responses

Response Schema: application/json
required
Array of objects (BulkAllocationResult)
allocated_count
required
integer
failed_count
required
integer
required
object (PaymentResponse)

The payment with its recomputed amount_allocated / amount_unallocated, so the caller needs no follow-up GET.

Request samples

Content type
application/json
{
  • "allocations": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "allocated_count": 0,
  • "failed_count": 0,
  • "payment": {
    }
}

List the invoices a payment could settle

Every invoice with an open balance that can still receive money — non-draft, non-cancelled — oldest due date first, with the payment's own currency first. Invoices in another currency are returned flagged rather than dropped: allocation refuses them, but an invoice the tenant can see in the invoice list must not vanish here unexplained. A payment the tenant received is offered invoices; one it paid out is offered credit notes.

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6
query Parameters
business_partner_id
string

Restrict candidates to one customer's invoices.

Responses

Response Schema: application/json
required
Array of objects (AllocationCandidate)
next_token
required
string or null

Always null — the open set is returned in one read.

truncated
required
boolean

True when the tenant has more open invoices than one read returns. A capped list presented as complete is how money gets allocated against a picture that is missing invoices, so the cap is stated rather than implied.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string",
  • "truncated": true
}

List payments the authenticated tenant received or paid out

Newest first by paid_at, both directions unless direction is given. Filters are applied after the page is read, so a page can come back short while next_token is still set — keep following the token until it is null. reference reads on until the page is full. direction reads on for at most ten underlying pages, so a page of one direction can still come back short or empty with next_token set.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

direction
string (PaymentDirection)
Enum: "incoming" "outgoing"

Only money received (incoming) or paid out (outgoing).

business_partner_id
string

Only payments from or to this partner.

allocation_state
string (AllocationState)
Enum: "unallocated" "partially_allocated" "allocated"

Only payments in this allocation state. unallocated is the work queue — money received that no invoice claims yet.

method
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at_from
string <date>

Inclusive lower bound on paid_at.

paid_at_to
string <date>

Inclusive upper bound on paid_at.

reference
string

Exact-match payment reference. Used to warn about a double-recorded payment; references are not unique, so this can legitimately return more than one row. With q, it narrows the search hits and ignores letter case.

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (PaymentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Record a payment received or paid out

Records money that moved — received unless direction is outgoing. It does not mark any invoice paid — allocate an incoming payment to an invoice separately. Supplying dedupe_key makes the create idempotent: a repeat returns the payment already recorded rather than recording the money twice.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (MonetaryAmountInput)

The amount that moved — received for an incoming payment, paid out for an outgoing one — as it appears on the bank statement or payment confirmation. Must be greater than zero. Where a customer withheld tax on an incoming payment, this is the net figure that arrived; the withheld part is recorded as a deduction on the allocation, not here.

direction
string (PaymentDirection)
Default: "incoming"
Enum: "incoming" "outgoing"

Which way the money went. incoming is money a customer paid the tenant; outgoing is money the tenant paid out. Set on create and never changed. Only an incoming payment can be allocated to an invoice.

object or null (SettledAmountInput)
method
string (PaymentMethod)
Default: "bank_transfer"
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
string <date>

Date the money was received (incoming) or paid out (outgoing). Defaults to today (UTC).

reference
string or null <= 200 characters

The reference the payment rail produced — an M-Pesa confirmation code, a UPI UTR, a Pix EndToEndId, a NIP session id, or a SEPA statement narrative. Free text: the formats share no structure across markets, so nothing is validated. Sized for the longest real value (the 140-character SEPA remittance field).

Reference (object) or null

Optional — the other party: who paid for an incoming payment, who was paid for an outgoing one. A payment may exist with no party set.

notes
string or null
dedupe_key
string or null [ 1 .. 64 ] characters

Optional. A second write with the same key within the tenant does not create a second row. The payment already recorded is returned unchanged.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Backend-composed label. A payment has no name field, so this is the amount plus the rail's own reference — recognisable in a picker or an approval card. Read the amount field to render the figure properly.

direction
required
string (PaymentDirection)
Enum: "incoming" "outgoing"

Which way the money went. incoming is money a customer paid the tenant; outgoing is money the tenant paid out. Set on create and never changed. Only an incoming payment can be allocated to an invoice.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
MonetaryAmount (object) or null

What the bank account moved, in the account's currency, when that differs from the payment currency. Informational only.

required
object (MonetaryAmount)

Backend-computed total applied to invoices. Maintained by the allocation transaction; never accepted on input.

required
object (MonetaryAmount)

Backend-computed remainder (amount − amount_allocated) — credit on account. Unlike a bare zero MonetaryAmount, this always carries the payment's currency, so a fully-allocated payment reads {"amount": 0, "currency": "KES"} rather than a null currency.

allocation_state
required
string (AllocationState)
Enum: "unallocated" "partially_allocated" "allocated"

How much of the payment has been applied to invoices. unallocated money is real money received that no invoice claims yet — credit on account against the payer.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

method
required
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
required
string <date>
reference
required
string or null
notes
required
string or null
dedupe_key
required
string or null
required
Reference (object) or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

self is the payment's own URL.

Request samples

Content type
application/json
{
  • "direction": "incoming",
  • "amount": {
    },
  • "settled_amount": {
    },
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "QGH7K3MNOP",
  • "business_partner": {
    },
  • "notes": "string",
  • "dedupe_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "pay_a1b2c3d4e5f6",
  • "_class": "payment",
  • "_name": "Acme Corp",
  • "direction": "incoming",
  • "amount": {
    },
  • "settled_amount": {
    },
  • "amount_allocated": {
    },
  • "amount_unallocated": {
    },
  • "allocation_state": "unallocated",
  • "allocation_version": 0,
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "string",
  • "notes": "string",
  • "dedupe_key": "string",
  • "business_partner": {
    },
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Get a payment

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Backend-composed label. A payment has no name field, so this is the amount plus the rail's own reference — recognisable in a picker or an approval card. Read the amount field to render the figure properly.

direction
required
string (PaymentDirection)
Enum: "incoming" "outgoing"

Which way the money went. incoming is money a customer paid the tenant; outgoing is money the tenant paid out. Set on create and never changed. Only an incoming payment can be allocated to an invoice.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
MonetaryAmount (object) or null

What the bank account moved, in the account's currency, when that differs from the payment currency. Informational only.

required
object (MonetaryAmount)

Backend-computed total applied to invoices. Maintained by the allocation transaction; never accepted on input.

required
object (MonetaryAmount)

Backend-computed remainder (amount − amount_allocated) — credit on account. Unlike a bare zero MonetaryAmount, this always carries the payment's currency, so a fully-allocated payment reads {"amount": 0, "currency": "KES"} rather than a null currency.

allocation_state
required
string (AllocationState)
Enum: "unallocated" "partially_allocated" "allocated"

How much of the payment has been applied to invoices. unallocated money is real money received that no invoice claims yet — credit on account against the payer.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

method
required
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
required
string <date>
reference
required
string or null
notes
required
string or null
dedupe_key
required
string or null
required
Reference (object) or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

self is the payment's own URL.

Response samples

Content type
application/json
{
  • "_id": "pay_a1b2c3d4e5f6",
  • "_class": "payment",
  • "_name": "Acme Corp",
  • "direction": "incoming",
  • "amount": {
    },
  • "settled_amount": {
    },
  • "amount_allocated": {
    },
  • "amount_unallocated": {
    },
  • "allocation_state": "unallocated",
  • "allocation_version": 0,
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "string",
  • "notes": "string",
  • "dedupe_key": "string",
  • "business_partner": {
    },
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Update a payment (alias of PATCH — only supplied fields change)

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6
Request Body schema: application/json
required
object (MonetaryAmountInput)

Request-side counterpart of MonetaryAmount. Identical, except that amount also accepts a quoted decimal string — the encoding the precision contract above tells clients to use for sub-cent values, which the server's Pydantic coerces to an exact Decimal.

Responses always carry amount as a JSON number; use MonetaryAmount for those.

object or null (SettledAmountInput)
method
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
string <date>
reference
string or null <= 200 characters
Reference (object) or null
notes
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Backend-composed label. A payment has no name field, so this is the amount plus the rail's own reference — recognisable in a picker or an approval card. Read the amount field to render the figure properly.

direction
required
string (PaymentDirection)
Enum: "incoming" "outgoing"

Which way the money went. incoming is money a customer paid the tenant; outgoing is money the tenant paid out. Set on create and never changed. Only an incoming payment can be allocated to an invoice.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
MonetaryAmount (object) or null

What the bank account moved, in the account's currency, when that differs from the payment currency. Informational only.

required
object (MonetaryAmount)

Backend-computed total applied to invoices. Maintained by the allocation transaction; never accepted on input.

required
object (MonetaryAmount)

Backend-computed remainder (amount − amount_allocated) — credit on account. Unlike a bare zero MonetaryAmount, this always carries the payment's currency, so a fully-allocated payment reads {"amount": 0, "currency": "KES"} rather than a null currency.

allocation_state
required
string (AllocationState)
Enum: "unallocated" "partially_allocated" "allocated"

How much of the payment has been applied to invoices. unallocated money is real money received that no invoice claims yet — credit on account against the payer.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

method
required
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
required
string <date>
reference
required
string or null
notes
required
string or null
dedupe_key
required
string or null
required
Reference (object) or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

self is the payment's own URL.

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "settled_amount": {
    },
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "string",
  • "business_partner": {
    },
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "_id": "pay_a1b2c3d4e5f6",
  • "_class": "payment",
  • "_name": "Acme Corp",
  • "direction": "incoming",
  • "amount": {
    },
  • "settled_amount": {
    },
  • "amount_allocated": {
    },
  • "amount_unallocated": {
    },
  • "allocation_state": "unallocated",
  • "allocation_version": 0,
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "string",
  • "notes": "string",
  • "dedupe_key": "string",
  • "business_partner": {
    },
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Partially update a payment

Payments are correctable in place. Lowering amount below amount_allocated is rejected with 422 — unallocate first.

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6
Request Body schema: application/json
required
object (MonetaryAmountInput)

Request-side counterpart of MonetaryAmount. Identical, except that amount also accepts a quoted decimal string — the encoding the precision contract above tells clients to use for sub-cent values, which the server's Pydantic coerces to an exact Decimal.

Responses always carry amount as a JSON number; use MonetaryAmount for those.

object or null (SettledAmountInput)
method
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
string <date>
reference
string or null <= 200 characters
Reference (object) or null
notes
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Backend-composed label. A payment has no name field, so this is the amount plus the rail's own reference — recognisable in a picker or an approval card. Read the amount field to render the figure properly.

direction
required
string (PaymentDirection)
Enum: "incoming" "outgoing"

Which way the money went. incoming is money a customer paid the tenant; outgoing is money the tenant paid out. Set on create and never changed. Only an incoming payment can be allocated to an invoice.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

required
MonetaryAmount (object) or null

What the bank account moved, in the account's currency, when that differs from the payment currency. Informational only.

required
object (MonetaryAmount)

Backend-computed total applied to invoices. Maintained by the allocation transaction; never accepted on input.

required
object (MonetaryAmount)

Backend-computed remainder (amount − amount_allocated) — credit on account. Unlike a bare zero MonetaryAmount, this always carries the payment's currency, so a fully-allocated payment reads {"amount": 0, "currency": "KES"} rather than a null currency.

allocation_state
required
string (AllocationState)
Enum: "unallocated" "partially_allocated" "allocated"

How much of the payment has been applied to invoices. unallocated money is real money received that no invoice claims yet — credit on account against the payer.

allocation_version
required
integer

Optimistic-lock counter for the allocation transaction. Read-only; exposed so a client can tell two allocation states apart.

method
required
string (PaymentMethod)
Enum: "bank_transfer" "bank_deposit" "cash" "card" "cheque" "mobile_money" "pix" "upi" "boleto" "other"

How the money moved. This is metadata about a payment that already happened — Raccoon does not process card, mobile-money, Pix, UPI or boleto transactions. bank_deposit is cash or a cheque paid in over the counter (distinct from cash in the till and from a bank_transfer); each value maps to a UNTDID 4461 payment-means code for e-invoice export.

paid_at
required
string <date>
reference
required
string or null
notes
required
string or null
dedupe_key
required
string or null
required
Reference (object) or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
object

self is the payment's own URL.

Request samples

Content type
application/json
{
  • "amount": {
    },
  • "settled_amount": {
    },
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "string",
  • "business_partner": {
    },
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "_id": "pay_a1b2c3d4e5f6",
  • "_class": "payment",
  • "_name": "Acme Corp",
  • "direction": "incoming",
  • "amount": {
    },
  • "settled_amount": {
    },
  • "amount_allocated": {
    },
  • "amount_unallocated": {
    },
  • "allocation_state": "unallocated",
  • "allocation_version": 0,
  • "method": "bank_transfer",
  • "paid_at": "2019-08-24",
  • "reference": "string",
  • "notes": "string",
  • "dedupe_key": "string",
  • "business_partner": {
    },
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Delete a payment

Only a payment with no live allocations can be deleted; one that is allocated to an invoice returns 409. Unallocate it first.

Authorizations:
BearerAuth
path Parameters
payment_id
required
string
Example: pay_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Bank Reconciliation

The camt statements this tenant has imported

Authorizations:
BearerAuth
query Parameters
q
string

Narrows the list to statements whose file name or uploader contains this term, in any case. It matches what the row shows and nothing else — status and counts are not free text. The whole set is read before the filter runs, so a term that matches nothing answers with an empty list, never a short page.

Responses

Response Schema: application/json
required
Array of objects (BankStatement)
next_token
required
string or null

Pass back as next_token for the following page. Null when done.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Import a camt statement

Opens an import and answers with where to upload the camt.053/054 file. The statement is created first, so a file can never sit in storage with nothing recording that it should be read — upload the bytes to the returned URL and there is nothing further to call.

Reading the file is a worker's job: a statement is megabytes of XML and one write per entry, which is not work a request should hold open.

Each credit is matched to an open payment collection by the structured reference it carries — never by payer name, amount or date, because a wrong automatic match moves money against the wrong invoice. A credit that matches nothing becomes an unallocated payment for a human to place.

Authorizations:
BearerAuth
Request Body schema: application/json
required
file_name
required
string
file_size
required
integer

Size in bytes. Refused above the registered cap for a statement.

mime_type
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
Reference (object) or null

Null only in the window between the statement being opened and its file row being created — a crash in between leaves a visible statement rather than an orphaned upload.

status
required
string
Enum: "awaiting_file" "in_progress" "finished" "failed"

awaiting_file — created, waiting for the upload to land. in_progress — the worker has picked the file up and is reading it. finished / failed — it is done.

Written only by the worker, through /status. The counts come from the entries callback and describe what was read; they do not decide what the import is doing.

credits_seen
required
integer
credits_matched
required
integer

Credits that carried a reference matching an open collection.

credits_unmatched
required
integer

Credits recorded as unallocated payments. Money that arrived with nothing to point it at is not an error — it is what the payments list is for.

debits_seen
required
integer

Outgoing entries kept from this file. They are stored as a record and nothing else — never matched, never a payment — so they are counted separately rather than folded into the credit tallies.

failure_reason
required
string or null
processed_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
object
required
object (PresignedPost)

S3 presigned-POST form. The client must POST multipart/form-data with every field from fields plus a final file part containing the binary body.

Request samples

Content type
application/json
{
  • "file_name": "august-2026.xml",
  • "file_size": 248000,
  • "mime_type": "application/xml"
}

Response samples

Content type
application/json
{
  • "_id": "bstm_9f2c1a4b7e05",
  • "_class": "string",
  • "file": {
    },
  • "status": "awaiting_file",
  • "credits_seen": 0,
  • "credits_matched": 0,
  • "credits_unmatched": 0,
  • "debits_seen": 0,
  • "failure_reason": "string",
  • "processed_at": 0,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    },
  • "upload": {
    }
}

One statement, and how its reading went

Authorizations:
BearerAuth
path Parameters
bank_statement_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
Reference (object) or null

Null only in the window between the statement being opened and its file row being created — a crash in between leaves a visible statement rather than an orphaned upload.

status
required
string
Enum: "awaiting_file" "in_progress" "finished" "failed"

awaiting_file — created, waiting for the upload to land. in_progress — the worker has picked the file up and is reading it. finished / failed — it is done.

Written only by the worker, through /status. The counts come from the entries callback and describe what was read; they do not decide what the import is doing.

credits_seen
required
integer
credits_matched
required
integer

Credits that carried a reference matching an open collection.

credits_unmatched
required
integer

Credits recorded as unallocated payments. Money that arrived with nothing to point it at is not an error — it is what the payments list is for.

debits_seen
required
integer

Outgoing entries kept from this file. They are stored as a record and nothing else — never matched, never a payment — so they are counted separately rather than folded into the credit tallies.

failure_reason
required
string or null
processed_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
object

Response samples

Content type
application/json
{
  • "_id": "bstm_9f2c1a4b7e05",
  • "_class": "string",
  • "file": {
    },
  • "status": "awaiting_file",
  • "credits_seen": 0,
  • "credits_matched": 0,
  • "credits_unmatched": 0,
  • "debits_seen": 0,
  • "failure_reason": "string",
  • "processed_at": 0,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Report where the import has got to (service-to-service)

The worker says it has picked the file up, and later that it is done. Service-gated for the same reason as the entries callback: a forged status tells a tenant their money has been looked at when it has not.

The only writer of status. The counts arrive through the entries callback and describe what was read; they do not decide what the import is doing.

Authorizations:
BearerAuth
path Parameters
bank_statement_id
required
string
Request Body schema: application/json
required
status
required
string
Enum: "in_progress" "finished" "failed"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
Reference (object) or null

Null only in the window between the statement being opened and its file row being created — a crash in between leaves a visible statement rather than an orphaned upload.

status
required
string
Enum: "awaiting_file" "in_progress" "finished" "failed"

awaiting_file — created, waiting for the upload to land. in_progress — the worker has picked the file up and is reading it. finished / failed — it is done.

Written only by the worker, through /status. The counts come from the entries callback and describe what was read; they do not decide what the import is doing.

credits_seen
required
integer
credits_matched
required
integer

Credits that carried a reference matching an open collection.

credits_unmatched
required
integer

Credits recorded as unallocated payments. Money that arrived with nothing to point it at is not an error — it is what the payments list is for.

debits_seen
required
integer

Outgoing entries kept from this file. They are stored as a record and nothing else — never matched, never a payment — so they are counted separately rather than folded into the credit tallies.

failure_reason
required
string or null
processed_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
object

Request samples

Content type
application/json
{
  • "status": "in_progress"
}

Response samples

Content type
application/json
{
  • "_id": "bstm_9f2c1a4b7e05",
  • "_class": "string",
  • "file": {
    },
  • "status": "awaiting_file",
  • "credits_seen": 0,
  • "credits_matched": 0,
  • "credits_unmatched": 0,
  • "debits_seen": 0,
  • "failure_reason": "string",
  • "processed_at": 0,
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Report the credits a statement contained (service-to-service)

The worker parses; this endpoint books. Gated to service identities and superusers only — a forged credit is money, so it is held to the tier a payment provider's callback uses.

Reporting the same credit twice books nothing twice: the bank's own reference for the entry is the idempotency key, which is what makes importing overlapping statements safe.

Authorizations:
BearerAuth
path Parameters
bank_statement_id
required
string
Request Body schema: application/json
required
Array of objects (BankTransactionCreate)
failure_reason
string or null

Responses

Response Schema: application/json
required
Array of objects

Request samples

Content type
application/json
{
  • "transactions": [
    ],
  • "failure_reason": "string"
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Entries seen on this tenant's account, and what became of them

Authorizations:
BearerAuth
query Parameters
status
string
Value: "unmatched"

unmatched narrows to money that arrived carrying no reference Raccoon recognised — the queue a human works through. Outgoing entries are excluded: a debit is never matched, so it is not waiting for anyone.

limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

The next_token from the previous page.

statement_id
string

Only the entries one imported file contained. The statement's own counts say how many there were; this is how to see them.

direction
string
Enum: "credit" "debit"

debit answers "what went out?". Outgoing entries are kept as a record only — never matched, never a payment. Both directions are returned when this is omitted.

Responses

Response Schema: application/json
required
Array of objects (BankTransaction)
next_token
required
string or null

Pass back as next_token for the following page. Null when done.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

One credit, by the reference its bank gave it

A transaction is addressed by its bank reference rather than by its own id: that is the key it is stored under, and the one anything holding a credit already knows.

Authorizations:
BearerAuth
path Parameters
bank_reference
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
bank_reference
required
string
required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

booked_on
required
string
direction
required
string
Enum: "credit" "debit"

Money in or money out. A debit is inert: it is never matched and never carries a payment, so its status is always unmatched.

status
required
string
Enum: "matched" "unmatched"
remittance_information
required
string or null
counterparty_name
required
string or null
required
Reference (object) or null
required
Array of objects (Reference)

The invoices this entry's money currently sits against, resolved from the live allocations rather than stored when the entry was booked — so a payment re-allocated or split afterwards answers with where the money is now. Each _name is the invoice number.

Empty for a debit — outgoing money is kept as a record and never matched to an invoice — and for a credit whose allocations have all been voided.

required
Reference (object) or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer
updated_at
required
integer
required
Reference (object) or null
required
object

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "string",
  • "bank_reference": "string",
  • "amount": {
    },
  • "booked_on": "string",
  • "direction": "credit",
  • "status": "matched",
  • "remittance_information": "string",
  • "counterparty_name": "string",
  • "invoices": [
    ],
  • "payment": {
    },
  • "statement": {
    },
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "_links": {
    }
}

Connectors

List the connectors offered to this tenant

The outside services this tenant can plug into: the ways their customers can pay an invoice from their phone, and the tax authorities that clear an invoice before it is valid. Which appear is derived from the tenant's country at read time, so a corrected market list reaches every tenant without a migration.

Every payment rail settles into the tenant's own merchant account — Raccoon never holds the funds. Connectors are switched on and off through their own tenant-config key, not here.

Authorizations:
BearerAuth
query Parameters
kind
string
Enum: "payment_rail" "clearance"

Only connectors of this kind.

Responses

Response Schema: application/json
required
Array of objects (Connector)
total
required
integer
page
required
integer
page_size
required
integer

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "page_size": 0
}

Read one connector's state for this tenant

Answers for any registered connector, including one not offered in the tenant's country — available_in_country carries that rather than the endpoint 404-ing, so a tenant who moved gets an explanation.

Authorizations:
BearerAuth
path Parameters
connector_id
required
string
Example: girocode

Responses

Response Schema: application/json
connector_id
required
string
kind
required
string
Enum: "payment_rail" "clearance"

What this connector connects to.

display_name
required
string
shape
required
string or null
Enum: "push" "qr" "link" null

How the buyer meets a payment rail. Null for other kinds.

reconciliation
required
string or null
Enum: "callback" "matched" null

callback — the rail confirms the payment itself. matched — it cannot, so the money is recognised by the reference it carries. Null for other kinds.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

The regime a clearance connector clears under, as it is stamped on the cleared invoice. Null for other kinds. Not the same identifier as connector_id: one regime may have more than one connector.

enabled
required
boolean

This connector's own enable key in the tenant's config.

configured
required
boolean

Whether anything is left for the tenant to do before this connector can be used: true once every required configuration field is on file. A connector with no required field — nothing to hand over — is configured by default. A missing IBAN and a missing API key are the same answer.

available_in_country
required
boolean

Whether the tenant's own country is one of the connector's default markets — where it is listed, defaults on, and shows a "configure" call-to-action. A soft default, not a usability gate: a payment rail switched on and configured can be collected on from any country (a clearance connector stays country-gated for legality).

required
Array of objects (ConnectorField)

What the tenant supplies to configure this connector — credentials, an IBAN. The configure screen renders from this rather than carrying its own copy of every connector's fields, so adding a connector stays a backend change. Empty for a connector with nothing to configure.

required
Array of objects (ConnectorRequirement)

What the connector needs on each invoice before it can run — a buyer phone for a rail that pushes a request to one. Distinct from a configuration field: checked against the invoice at collection time rather than supplied once. Empty when the connector needs nothing beyond being configured.

description
string

Response samples

Content type
application/json
{
  • "connector_id": "mpesa_push",
  • "kind": "payment_rail",
  • "display_name": "M-Pesa request on the phone",
  • "shape": "push",
  • "reconciliation": "callback",
  • "clearance_scheme": "ke_kra_etims",
  • "enabled": true,
  • "configured": true,
  • "available_in_country": true,
  • "config_fields": [
    ],
  • "requirements": [
    ],
  • "description": "string"
}

Switch a connector on or off for this tenant

Whether the tenant may use this connector at all — the first of the three axes, and a separate control from its credentials. A connector switched off leaves the surfaces that offer it; one switched on without credentials stays visible with something to do.

The connector owns its own switch rather than exposing the tenant_config key behind it, so no caller has to name that key. The key's own edit scope still decides who may flip it.

Authorizations:
BearerAuth
path Parameters
connector_id
required
string
Example: girocode
Request Body schema: application/json
required
enabled
required
boolean

Responses

Response Schema: application/json
connector_id
required
string
kind
required
string
Enum: "payment_rail" "clearance"

What this connector connects to.

display_name
required
string
shape
required
string or null
Enum: "push" "qr" "link" null

How the buyer meets a payment rail. Null for other kinds.

reconciliation
required
string or null
Enum: "callback" "matched" null

callback — the rail confirms the payment itself. matched — it cannot, so the money is recognised by the reference it carries. Null for other kinds.

clearance_scheme
required
string or null
Enum: "ke_kra_etims" "ng_firs_mbs" "in_gstn_irp" "br_sefaz_nfe" null

The regime a clearance connector clears under, as it is stamped on the cleared invoice. Null for other kinds. Not the same identifier as connector_id: one regime may have more than one connector.

enabled
required
boolean

This connector's own enable key in the tenant's config.

configured
required
boolean

Whether anything is left for the tenant to do before this connector can be used: true once every required configuration field is on file. A connector with no required field — nothing to hand over — is configured by default. A missing IBAN and a missing API key are the same answer.

available_in_country
required
boolean

Whether the tenant's own country is one of the connector's default markets — where it is listed, defaults on, and shows a "configure" call-to-action. A soft default, not a usability gate: a payment rail switched on and configured can be collected on from any country (a clearance connector stays country-gated for legality).

required
Array of objects (ConnectorField)

What the tenant supplies to configure this connector — credentials, an IBAN. The configure screen renders from this rather than carrying its own copy of every connector's fields, so adding a connector stays a backend change. Empty for a connector with nothing to configure.

required
Array of objects (ConnectorRequirement)

What the connector needs on each invoice before it can run — a buyer phone for a rail that pushes a request to one. Distinct from a configuration field: checked against the invoice at collection time rather than supplied once. Empty when the connector needs nothing beyond being configured.

description
string

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "connector_id": "mpesa_push",
  • "kind": "payment_rail",
  • "display_name": "M-Pesa request on the phone",
  • "shape": "push",
  • "reconciliation": "callback",
  • "clearance_scheme": "ke_kra_etims",
  • "enabled": true,
  • "configured": true,
  • "available_in_country": true,
  • "config_fields": [
    ],
  • "requirements": [
    ],
  • "description": "string"
}

What is known about this connector's stored credentials

Metadata only. No human tier can read a secret value back once saved: the record carries it as ciphertext and never as plaintext. The one route that returns the values is GET .../credentials/values, which is callable by a registered service and by nobody else.

Authorizations:
BearerAuth
path Parameters
connector_id
required
string
Example: mpesa_push

Responses

Response Schema: application/json
connector_id
required
string
configured
required
boolean

Whether credentials are on file for this connector.

object

The connector's non-secret fields, as the tenant entered them.

verified_at
integer or null

When the credentials were last confirmed to work, as a unix timestamp. Null means they have not been checked — which is not the same as broken.

verification_error
string or null

Why the last check failed, when it did.

updated_at
integer or null

Response samples

Content type
application/json
{
  • "connector_id": "mpesa_push",
  • "configured": true,
  • "hint": {
    },
  • "verified_at": 0,
  • "verification_error": "string",
  • "updated_at": 0
}

Store this tenant's own credentials for a connector

Replaces the whole credential set and then checks that it works. The credentials belong to the tenant's own relationship with the provider or the tax authority — Raccoon uses them to act on the tenant's behalf, and never holds their money.

Authorizations:
BearerAuth
path Parameters
connector_id
required
string
Example: mpesa_push
Request Body schema: application/json
required
required
object non-empty

Field id to value. Every required field the connector declares must be present; optional ones may be included. Unknown fields, a missing required one, or a value that fails the field's format check are rejected.

Responses

Response Schema: application/json
connector_id
required
string
configured
required
boolean

Whether credentials are on file for this connector.

object

The connector's non-secret fields, as the tenant entered them.

verified_at
integer or null

When the credentials were last confirmed to work, as a unix timestamp. Null means they have not been checked — which is not the same as broken.

verification_error
string or null

Why the last check failed, when it did.

updated_at
integer or null

Request samples

Content type
application/json
{
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "connector_id": "mpesa_push",
  • "configured": true,
  • "hint": {
    },
  • "verified_at": 0,
  • "verification_error": "string",
  • "updated_at": 0
}

Forget this connector's credentials

Removes the stored values immediately. The connector stays switched on and becomes unconfigured again, so it keeps its place in the list with something to do rather than disappearing.

Authorizations:
BearerAuth
path Parameters
connector_id
required
string
Example: mpesa_push

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Resolve a connector's credentials for a worker service

Returns the plaintext credentials, and is the only route that does.

It exists because an adapter running outside the core cannot resolve them in process — a service may not import core code, and the stored values are ciphertext — so a clearance worker has no other way to authenticate its one call to the tax authority.

Callable only by a registered service: no administrator, owner or ordinary user reaches it at any tier. Each service is additionally pinned to the connectors it may resolve by the scope table in middleware/service_auth.py, so a payment adapter cannot read a tax authority's credentials or the reverse.

Authorizations:
BearerAuth
path Parameters
connector_id
required
string
Example: nrs_mbs

Responses

Response Schema: application/json
connector_id
required
string
required
object

Every field the connector declares, secret and non-secret alike.

Response samples

Content type
application/json
{
  • "connector_id": "nrs_mbs",
  • "values": {
    }
}

Documents

List documents for an invoice

Returns all document rows attached to the invoice. A document is a derived business document (invoice PDF, delivery slip, offer, …) generated asynchronously by a worker.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (DocumentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a document for an invoice

Creates a document row in pdf_pending and emits a document.created event. The PDF generation worker subscribes and asynchronously attaches the rendered file — clients should poll the row until status flips to pdf_ready. An invoice_ubl for an invoice in a currency with three decimals is refused with 422 invoices.e_invoice_three_decimal_currency: EN 16931 amounts have at most two.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
document_type
required
string (DocumentType)
Enum: "invoice" "invoice_ubl" "delivery_slip" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. invoice renders a PDF. invoice_ubl renders the same invoice as a Peppol BIS Billing 3.0 (UBL 2.1) XML file, the structured form EN 16931 requires; it is generated beside the PDF, never instead of it. The remaining values are reserved for upcoming templates. An offer's PDF is not here: an offer is its own record with its own documents, under /resource/v1/offers/{id}/documents.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "invoice_ubl" "delivery_slip" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. invoice renders a PDF. invoice_ubl renders the same invoice as a Peppol BIS Billing 3.0 (UBL 2.1) XML file, the structured form EN 16931 requires; it is generated beside the PDF, never instead of it. The remaining values are reserved for upcoming templates. An offer's PDF is not here: an offer is its own record with its own documents, under /resource/v1/offers/{id}/documents.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "document_type": "invoice"
}

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Get a single document

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string
Example: doc_a1b2c3d4e5f67890

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "invoice_ubl" "delivery_slip" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. invoice renders a PDF. invoice_ubl renders the same invoice as a Peppol BIS Billing 3.0 (UBL 2.1) XML file, the structured form EN 16931 requires; it is generated beside the PDF, never instead of it. The remaining values are reserved for upcoming templates. An offer's PDF is not here: an offer is its own record with its own documents, under /resource/v1/offers/{id}/documents.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Partial update — attach the rendered PDF, or retry a failed one

Two mutable fields, file and status. Setting file on a pdf_pending document implicitly transitions it to pdf_ready. Setting status to pdf_pending moves a pdf_failed document back to pending and re-publishes the document.created event so the worker picks it up again — idempotent for an already-pending row. No other status is writable; the rest of the FSM is server-controlled. Used by the invoice-document-generator service to report a rendered PDF (per architecture.md § Async Workers — no internal API; a UI client could call it too). Requires admin/superuser role. Idempotent: replaying on an already-attached document returns 200 with the existing row (the originally attached PDF is preserved). Per architecture.md § Embedded References, only _id is required inside the file Reference; _class and _name are accepted and resolved server-side from the linked File row.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string
Example: doc_a1b2c3d4e5f67890
Request Body schema: application/json
required
Reference (object) or null
status
string
Value: "pdf_pending"

Set to pdf_pending to re-request the render of a pdf_failed document. Idempotent for an already-pending row; 422 from any other status, and 422 when sent together with file — those are two different writes.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "invoice_ubl" "delivery_slip" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. invoice renders a PDF. invoice_ubl renders the same invoice as a Peppol BIS Billing 3.0 (UBL 2.1) XML file, the structured form EN 16931 requires; it is generated beside the PDF, never instead of it. The remaining values are reserved for upcoming templates. An offer's PDF is not here: an offer is its own record with its own documents, under /resource/v1/offers/{id}/documents.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "file": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    },
  • "created_by": {
    }
}

Delete a document

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string
Example: doc_a1b2c3d4e5f67890

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Email

List the tenant's business email, newest first

The shared mailbox, readable by every signed-in user of the tenant. Nothing here is filtered by user.

Bodies are never in a list response — they live in a sibling row and are returned by the detail route. preview is the one line that makes the list readable without them.

Every filter except linked_to is applied after the query rather than by an index, so a page can come back short — or empty — while next_token is still set. Exhaustion is a null token, never a short page.

linked_to is read from the record's own link rows instead, so its cost is the record's mail, not the mailbox. It takes no other filter and answers null counts.

todo_counts rides this response so the queue's three sections can be labelled from one call. It is tallied on the first page only and is null on a continuation page or with include_counts=false: the headings do not change while paging, and the tally walks the tenant's whole partition.

Authorizations:
BearerAuth
query Parameters
direction
string
Enum: "inbound" "outbound"
todo_kind
string (TodoKind)
Enum: "action" "reply" "notice"

Only messages of this kind.

todo_status
string (TodoStatus)
Enum: "open" "done"

Only messages anyone has, or has not, dealt with.

archived
string
Enum: "true" "false"

false (the default) leaves archived messages out, true lists only the archived ones. The counts follow the same filter. Mail listed for one record (linked_to) always includes archived mail.

assignee
string

Only the messages one person holds. A user id, me for the calling user, or none for the work nobody has picked up. This narrows the answer, never the reader: without it every signed-in user sees the whole mailbox, and with it they still may.

linked_to
string^(invoice|offer):.+$

<class>:<id>, e.g. invoice:inv_a1b2c3d4e5f6. Only messages settled onto that record — a send, tag or manual link — newest first. A header link is a guess waiting for an answer and is not listed here; read it with link_state=linked. Takes no other filter; drafts are never listed.

link_state
string
Enum: "linked" "unlinked"

linked: the message names a record. unlinked: it names none.

status
string
Value: "draft"

draft lists the unsent drafts (drafting and draft) instead of the mail. Drafts are never in the mail list, and with this filter todo_counts is null: a draft is not a to-do.

thread_of
string
Example: thread_of=eml_a1b2c3d4e5f6

Read the conversation this message belongs to instead of the mailbox: its messages oldest first, sent mail and drafts included, in one page — next_token is null and the counts are null. Grouped by thread_token, then by the In-Reply-To / References chain and the message a reply answers. Tenant-scoped: an id from another tenant answers 404. Refused with 422 alongside direction, linked_to, link_state, todo_kind, todo_status, assignee, status or next_token. Up to 100 messages.

include_counts
string
Default: "true"
Enum: "true" "false"

false skips the todo_counts tally, which walks the tenant's whole mailbox, and answers null for todo_counts and todo_counts_are_a_floor as a continuation page does. For a caller that reads the rows and not the section headings.

limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (EmailMessageListItem)
next_token
required
string or null
required
TodoCounts (object) or null

Tallied on the first page only, and null on a continuation page — the section headings do not change while paging, and the tally walks the tenant's partition, so recomputing it per page turn would cost more than the page. A client keeps the counts it already has.

todo_counts_are_a_floor
required
boolean or null

The counting walk hit its row budget with rows left, so each count is at least what it says rather than exactly. False for any mailbox a tenant is likely to have, and null wherever todo_counts is.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string",
  • "todo_counts": {
    },
  • "todo_counts_are_a_floor": true
}

Record a message (internal — service callers only)

Internal. Called by the mail worker holding a service identity, never by a tenant: a tenant token is refused with 403.

This is the only write on the message itself. The envelope, headers, verdicts, bodies and attachments are a record of what arrived or was sent, and a record the recipient can edit is not a record — so there is no tenant-facing POST, PUT or DELETE here at all, and the one tenant-facing PATCH takes the to-do and refuses every other key.

Two bounds are applied server-side rather than asserted by the caller: the references chain is cut to 20 entries, and the bodies are truncated to their inline caps with the full copy written to S3. Both truncate and neither rejects — the message already arrived.

An inbound message must carry recipient, the envelope address it was delivered to. The core resolves it against the alias claims and refuses the message with 403 unless it belongs to the token's tenant, so the tenant a message lands in is decided here and never by the caller. Its sub-address tag becomes thread_token; an inbound caller may not send one.

A thread — the tag, or the sender when there is none — may add 20 inbound messages per UTC day; past that the answer is 429 and the worker drops the message. A dedupe_key seen before answers 200 with the message it stored.

Authorizations:
ServiceToken
Request Body schema: application/json
required
direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string <= 320 characters
from_name
string or null <= 320 characters
to
Array of strings <= 100 items
cc
Array of strings <= 100 items
subject
string <= 998 characters
preview
string or null <= 400 characters

The one line the list shows. Derived from the plain-text body when omitted.

message_id
string or null <= 998 characters
in_reply_to
string or null <= 998 characters
references
Array of strings

The References header chain, oldest first. Kept to the newest 20 entries — a long thread's chain runs to tens of kilobytes, and the newest entries are the ones that name the message being answered.

reply_to
Array of strings <= 5 items [ items <= 254 characters ]

The Reply-To addresses of an inbound message, only those that parse as plain addresses. Refused on an outbound message.

spf_verdict
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

TodoKind (string) or null

What the message is for. The only to-do field a writer may state; omitted, it follows the direction — reply inbound, notice outbound. Whether anyone still has to act on it is derived, never supplied.

Array of objects (EmailLinkCreate) <= 20 items

The records this message is about. Each record at most once. An outbound message's links have source send; a received one's never do.

thread_token
string or null <= 64 characters
raw_mime_key
string or null <= 1024 characters
raw_mime_expires_at
integer or null

Unix seconds. Past this the API serves a null raw_mime_key.

EmailBodyCreate (object) or null
recipient
string or null <= 320 characters

The envelope address the message was delivered to, not a header. Required on an inbound message; decides the tenant and the thread token, and is not stored.

dedupe_key
string or null [ 1 .. 128 ] characters

Reserved together with the message. A second call with the same key answers 200 with the stored message.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null

Request samples

Content type
application/json
{
  • "direction": "inbound",
  • "status": "received",
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "todo_kind": "action",
  • "links": [
    ],
  • "thread_token": "string",
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "body": {
    },
  • "recipient": "string",
  • "dedupe_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Which tenant an inbound address belongs to (internal — service callers only)

Internal. Called by the inbound-mail worker with a token for the system tenant, which holds the alias claims; any other tenant is refused with 403. The address is split on its first +, the base is case-folded and looked up in the claims. A released alias keeps answering for as long as its claim is held.

404 for an address outside the mail domain, one the alias grammar does not admit, and one nobody holds — the worker drops all three. The address travels in the body so it never lands in an access log.

Authorizations:
ServiceToken
Request Body schema: application/json
required
address
required
string [ 3 .. 320 ] characters

Responses

Response Schema: application/json
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

local_part
required
string

The claimed base, case-folded, without its tag.

tag
required
string or null

What followed the first +, as sent.

Request samples

Content type
application/json
{
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "local_part": "string",
  • "tag": "string"
}

Read one message, with its bodies and attachment details

content_type and size are joined onto each attachment here because the file rows are one read away on the server and cost a round trip each from a browser.

body.body_html is sanitised before it is stored, but it still comes from an untrusted sender. Render it as untrusted content.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
EmailBody (object) or null
required
SuggestedAction (object) or null
required
Array of objects (Reference)

The earlier emails the agent was given to write this draft, oldest first: for a reply, the conversation up to the message it answers. Empty for a template draft, while the draft is drafting, and for mail that was never an agent's draft. Set by the server; _name is the email's subject as it was when the draft was written.

send_reply_to
required
string or null

Where an answer to this reply draft would go, the Reply-To it is sent with. null for anything that is not a reply draft, and when an answer would reach nobody.

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "send_reply_to": "string",
  • "draft_context": [
    ],
  • "suggested_action": {
    },
  • "body": {
    }
}

Assign the message's to-do or complete it, edit a draft, or send a reply draft

Three shapes. The to-do update takes assignee, todo_status and archived and refuses every other key with a 422, so the envelope, headers, verdicts and bodies stay what the worker wrote.

A body naming to, cc, subject or body edits a draft: allowed only while the message is an outbound draft, 409 otherwise. Once queued the content is frozen. To and Cc together hold at most 10 addresses; more answers 422 with reason: too_many_recipients.

{"status": "queued"} sends a reply draft, optionally with the draft_version the caller read. It answers 200 with the message, queued; the worker sends it after the response. No correspondence row is written. Refusals, with nothing queued:

  • 422 for a document draft (no replied_message): send it from its invoice or offer.
  • 409 reason: already_sent for mail that is queued, sent or failed. A failed reply is not sent again; POST .../replies opens a new draft.
  • 409 reason: not_a_draft for anything else that is not an outbound draft, a draft still drafting included.
  • 409 reason: draft_changed when the draft's text or links changed since draft_version was read, or between the read and the write.
  • 422 for a draft with no To, and 422 reason: too_many_recipients for more than 10 addresses in To and Cc together.
  • 429 reason: tenant_outbound_cap_reached over the plan's daily limit of outgoing emails, and 409 asking to send again when two sends collide on that count after two retries.

Any signed-in user of the tenant may assign or complete any message, including one somebody else owns. Assignment says who picked the work up; it is not a permission and it narrows nobody's view.

An omitted field is left alone. assignee: null hands the message back to the queue. Completing stamps done_by and done_at with the caller and the moment; reopening clears both. archived: true stamps archived_at, false clears it; archiving is allowed on any message that is not a draft.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6
Request Body schema: application/json
required
One of
Reference (object) or null

The user who owns this message, or null for nobody.

todo_status
string
Enum: "open" "done"

Omit it to leave the status alone. There is no null status, so an explicit null is refused rather than answering 200 having changed nothing — unlike assignee, where null is the real hand-back to the queue.

archived
boolean

true archives the message, false brings it back to the mailbox. Omit it to leave the message alone; an explicit null is refused.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null

Request samples

Content type
application/json
Example
{
  • "assignee": {
    },
  • "todo_status": "open",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a draft or a received message

Deletes an outbound message in drafting or draft, or a message that was received (received or quarantined), with its body, its record links and its attachments. The send dialog calls it when a draft it created is closed without an edit. Mail that was queued, sent or failed cannot be deleted: 409. A received message cannot be brought back.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Confirm or reject a record a received message is linked to

A received message is linked to a record by the sub-address tag of our own Reply-To (tag, settled) or by its In-Reply-To / References headers (header, a guess — Outlook regenerates them and a forward carries stale ones). This route answers the guess.

{"confirmed": true} makes the link's source manual. {"confirmed": false} removes the link and stores the rejection, so the pair is never linked again. Both answers emit a change event carrying the actor. record names the link; without it the one guess is answered, or the one link when there is no guess.

Only the links are written; the envelope, headers and bodies stay what the worker stored. Confirming a settled link writes nothing and answers the row. 422 for a sent message, whose link is the document it was sent about, for a message with no link, and for a message with several links when record is left out. 409 when the link changed while it was being answered.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6
Request Body schema: application/json
required
confirmed
required
boolean

true settles the link: its source becomes manual and the message is listed on the record. false removes the link and stores the rejection, so the product never links this message to that record again.

object (Reference)

Which link is answered. May be left out while the message has one guess, or one link and no guess.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null

Request samples

Content type
application/json
{
  • "confirmed": true,
  • "record": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Link a message to a record it is about

A person saying the message concerns record. A message may be about up to 20 records. The link is stored as manual and the message is listed on the record (GET /resource/v1/emails?linked_to=).

Idempotent: a link already settled writes nothing and answers the row. A guess on the same record is settled, and an earlier rejection of it is taken back. The record is read in the caller's tenant, so a record of another tenant is a 422 like one that does not exist.

409 reason: links_locked_while_sending while the message is queued. On a draft the change counts in draft_version.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null

Request samples

Content type
application/json
{
  • "record": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Say a message is not about a record

The link goes and the record is stored as rejected, so the product never links this message to it again. Idempotent: a link the message does not have writes nothing. 422 for the document an outbound message was sent about (source send), which is a fact about the send. Answers the message rather than 204, so the caller sees the links that are left. 409 reason: links_locked_while_sending while the message is queued. On a draft the change counts in draft_version.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6
record_id
required
string^(inv|off)_.+$
Example: inv_a1b2c3d4e5f6

The linked record's id. A message links a record at most once, and the id's prefix names its class (inv_ invoice, off_ offer); an id with any other prefix is a 422.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects (Reference)

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Open the reply draft to a received message

Creates the reply draft to a received message, or answers the unsent one already open for it — 201 for a new draft, 200 for the open one, whose link is first set to what a new draft would get, so a link changed on the message since holds for the reply. body, when given, sets its text. Without draft_generator no model is called: a new draft holds the body, or nothing, and its draft_generator is null.

With draft_generator: agent, a new draft is written for the user by the same rule as the send dialog's (invoice.delivery.agent_email_drafts on, a draft writer configured, the agent allowance not spent). The agent's draft comes back drafting with draft_generator: agent, an empty body and the Re: subject; follow it with GET /resource/v1/emails/{id} until it is draft, when the body answers the message and draft_context names the emails it was written from. The writer is given the conversation up to the message answered and the facts of the invoice or offer the message has a settled link to, none for a message linked to nothing; a body naming any figure that is neither one of those facts nor in the tenant's own tonality or sample email is thrown away. Otherwise, whenever the agent cannot write it, and with draft_generator: template, the draft is draft with draft_generator: template: a greeting and a sign-off in the document's language, else the tenant's. A draft is never left in an error, and while it is drafting it cannot be edited. An open draft whose link is set while the agent writes it ends as the template's.

A new draft goes to the sender only: the message's reply_to addresses when it has any, else from_address; nobody on Cc. The subject gets Re: unless it already starts with a reply prefix (Re:, AW:, Antw:, SV:, TR:). in_reply_to is the message's message_id, references is its chain plus that id, its one link, with source send, is the message's first settled link (else its guessed one), replied_message points at it, and thread_token is the conversation's, so the reply is the last row of GET /resource/v1/emails?thread_of=…. A message linked to no invoice or offer, such as a question from someone who is not a customer yet, gets a draft linked to nothing. send_reply_to says where the sender's answer to the reply will go.

Edit the draft with PATCH /resource/v1/emails/{id}, throw it away with DELETE, and send it with PATCH /resource/v1/emails/{id} {"status": "queued"}. A new draft with no text expires after 30 days unless it is edited, like any draft. A reply whose send failed is not sent again: this route then opens a new draft.

422 for a message the tenant sent (emails.reply_to_outbound), for one quarantined as malformed (emails.reply_to_quarantined) and for a body sent together with a draft_generator, and when the open draft has no room left for the message's link (emails.too_many_links). 409 for a body while the open draft is still drafting (emails.draft_being_written), when the open draft was queued meanwhile (emails.not_a_draft), and when its links keep changing while its link is set (emails.document_link_changed). The open draft is found through an eventually consistent index, so two requests in the same instant can open two drafts.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6
Request Body schema: application/json
optional
body
string or null

Plain text, at most 16384 bytes in UTF-8.

draft_generator
string or null
Enum: "agent" "template" null

Who writes a new draft, in the vocabulary of the draft's own draft_generator. agent: the agent, when the tenant has invoice.delivery.agent_email_drafts on, a draft writer is configured and the agent allowance is not spent; the draft comes back drafting. Otherwise the template writes it. template: a greeting and a sign-off, at once. Ignored when a reply draft is already open: that one is returned as it is.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
EmailBody (object) or null
required
SuggestedAction (object) or null
required
Array of objects (Reference)

The earlier emails the agent was given to write this draft, oldest first: for a reply, the conversation up to the message it answers. Empty for a template draft, while the draft is drafting, and for mail that was never an agent's draft. Set by the server; _name is the email's subject as it was when the draft was written.

send_reply_to
required
string or null

Where an answer to this reply draft would go, the Reply-To it is sent with. null for anything that is not a reply draft, and when an answer would reach nobody.

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string

The subject line.

required
object

self is the message's own resource URL. An attachment is fetched from /resource/v1/emails/{id}/attachments/{file_id}. Further rels may be present; a client follows the ones it knows.

direction
required
string
Enum: "inbound" "outbound"
status
required
string (EmailStatus)
Enum: "received" "sent" "failed" "queued" "quarantined" "drafting" "draft"

drafting and draft are outbound messages nobody has sent yet: drafting is still being written by a generator, draft can be edited. A send moves a draft to queued, after which the content is frozen; the worker then sets sent or failed. Drafts are left out of the mail list and its counts unless status=draft asks for them.

from_address
required
string
from_name
required
string or null
to
required
Array of strings
cc
required
Array of strings
subject
required
string
preview
required
string

One line of the message, so the list reads without fetching bodies.

message_id
required
string or null
in_reply_to
required
string or null
references
required
Array of strings
reply_to
required
Array of strings

Where the sender asked replies to go. Sender-controlled, so it is text, not a confirmed identity. Empty when the message had no Reply-To, and always empty on an outbound message.

spf_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dkim_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

dmarc_verdict
required
string (EmailVerdict)
Enum: "pass" "fail" "gray" "processing_failed" "not_available"

An authentication result reported by the receiving mail service. SPF and DKIM are recorded and never gate; a message is not authenticated by its From header alone.

blocked_remote_reference_count
required
integer
attachment_count
required
integer

0 on a stored row, for the reason attachments is empty. The detail response recomputes it from the file rows.

required
Array of objects

Always empty on a stored row: nothing can write it, because a file's parent is the message and the message is minted before any file exists. The detail response replaces it with the files actually parented on the message, which is the tenant-isolated fact.

todo_kind
required
string (TodoKind)
Enum: "action" "reply" "notice"

What the message is for. action is something Raccoon can do, reply something only a person can answer, notice a message that needs nothing. Every stored message carries one; there is no absent state, and it is not editable.

todo_status
required
string (TodoStatus)
Enum: "open" "done"

Whether anyone has dealt with the message. Not a read flag — a shared queue needs one answer to "has anyone dealt with this", not one per person. An outbound message is done when it is recorded.

required
Reference (object) or null

Who has picked this message up, or null while nobody has. Never a permission: every signed-in user of the tenant can read, open, re-assign and complete any message whoever owns it.

required
Reference (object) or null

Who completed it. Null on an outbound message, which is done because it was sent rather than because anyone cleared it.

done_at
required
integer or null

Unix epoch seconds.

archived
required
boolean

Whether the message is archived. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

archived_at
required
integer or null

Unix epoch seconds when somebody archived the message, null while it is in the mailbox. Archived mail stays readable and linked to its records; the list leaves it out unless asked with archived=true.

required
Array of objects (EmailLink) <= 20 items

The records this message is about. A single-record view shows the first settled link, else the first guess.

failure_reason
required
string or null

Why an outbound message failed, as a code, not a translated sentence: the provider's own error code, or one of Raccoon's own — send_unconfirmed (no outcome was recorded; it may have been sent) and send_not_started (no worker started the send; nothing was sent). null on anything that is not failed.

sent_at
required
integer or null

Unix epoch seconds the channel accepted an outbound message. Set when the message becomes sent and kept if a later bounce fails it; null on received mail and on a message never sent.

draft_generator
required
string or null
Enum: "template" "agent" null

What wrote a draft: the fixed template text or the agent. null on mail that was never a draft.

draft_version
required
integer

Counts the writes to a draft's text and links. Pass it when sending a reply draft, so a draft changed since it was read is not sent.

thread_token
required
string or null

The conversation this message belongs to: the sub-address tag a received message came in on, or the token a send and its replies went out under.

required
Reference (object) or null

On a reply draft or sent reply, the received message it answers. Null on everything else.

raw_mime_key
required
string or null

Null once the 90-day retention has passed, rather than a key whose object no longer exists.

raw_mime_expires_at
required
integer or null
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
Reference (object) or null
required
EmailBody (object) or null
required
SuggestedAction (object) or null
required
Array of objects (Reference)

The earlier emails the agent was given to write this draft, oldest first: for a reply, the conversation up to the message it answers. Empty for a template draft, while the draft is drafting, and for mail that was never an agent's draft. Set by the server; _name is the email's subject as it was when the draft was written.

send_reply_to
required
string or null

Where an answer to this reply draft would go, the Reply-To it is sent with. null for anything that is not a reply draft, and when an answer would reach nobody.

Request samples

Content type
application/json
{
  • "body": "string",
  • "draft_generator": "agent"
}

Response samples

Content type
application/json
{
  • "_id": "eml_a1b2c3d4e5f6",
  • "_class": "email_message",
  • "_name": "string",
  • "_links": {
    },
  • "tenant": {
    },
  • "direction": "inbound",
  • "status": "received",
  • "draft_generator": "template",
  • "draft_version": 0,
  • "from_address": "string",
  • "from_name": "string",
  • "to": [
    ],
  • "cc": [
    ],
  • "subject": "string",
  • "preview": "string",
  • "message_id": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "reply_to": [
    ],
  • "spf_verdict": "pass",
  • "dkim_verdict": "pass",
  • "dmarc_verdict": "pass",
  • "blocked_remote_reference_count": 0,
  • "attachment_count": 0,
  • "attachments": [
    ],
  • "todo_kind": "action",
  • "todo_status": "open",
  • "assignee": {
    },
  • "done_by": {
    },
  • "done_at": 0,
  • "archived": true,
  • "archived_at": 0,
  • "links": [
    ],
  • "failure_reason": "string",
  • "sent_at": 0,
  • "thread_token": "string",
  • "replied_message": {
    },
  • "raw_mime_key": "string",
  • "raw_mime_expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "send_reply_to": "string",
  • "draft_context": [
    ],
  • "suggested_action": {
    },
  • "body": {
    }
}

Download one attachment of one message

Ordinary bearer auth. Answers a presigned URL rather than the bytes, like every other file download.

The file must be an attachment of this message: without that check the route would be a way to read any file in the tenant through a message id.

Authorizations:
BearerAuth
path Parameters
email_message_id
required
string
Example: eml_a1b2c3d4e5f6
file_id
required
string
Example: fil_a1b2c3d4e5f6

Responses

Response Schema: application/json
url
required
string

Presigned S3 URL for the attachment.

expires_at
required
integer

Unix epoch seconds after which the URL stops working.

Response samples

Content type
application/json
{
  • "url": "string",
  • "expires_at": 0
}

Projects

List projects for the authenticated tenant

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (ProjectResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a project

Authorizations:
BearerAuth
Request Body schema: application/json
required
title
required
string [ 1 .. 200 ] characters
type_id
string [ 1 .. 100 ] characters

The project-class tenant type this project is created under. Every project has one. Omitted, the project is created under the tenant's default project type; that is a 422 when the tenant has several and marks none of them default.

schema_version
string or null

Type version. Omitted = latest.

object

Custom field values keyed by section field IDs.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the project's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

title
required
string
type_id
required
string

The project-class tenant type this project was created under.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object

Custom field values; {} when the type declares no fields

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Request samples

Content type
application/json
{
  • "title": "Q2 2026 Launch",
  • "type_id": "client_engagement",
  • "schema_version": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prj_a1b2c3d4e5f6",
  • "_class": "project",
  • "_name": "Acme Corp",
  • "title": "string",
  • "type_id": "string",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the project's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

title
required
string
type_id
required
string

The project-class tenant type this project was created under.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object

Custom field values; {} when the type declares no fields

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prj_a1b2c3d4e5f6",
  • "_class": "project",
  • "_name": "Acme Corp",
  • "title": "string",
  • "type_id": "string",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Partially update a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6
Request Body schema: application/json
required
title
string [ 1 .. 200 ] characters
type_id
string or null
schema_version
string or null
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the project's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

title
required
string
type_id
required
string

The project-class tenant type this project was created under.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object

Custom field values; {} when the type declares no fields

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Request samples

Content type
application/json
{
  • "title": "string",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "prj_a1b2c3d4e5f6",
  • "_class": "project",
  • "_name": "Acme Corp",
  • "title": "string",
  • "type_id": "string",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Custom Objects

List a tenant type's custom objects (type-scoped, name-sorted)

Lists the custom objects of one tenant custom_object-class type. The type query parameter is required — objects are only ever viewed within their type group, and the query is strongly consistent.

Authorizations:
BearerAuth
query Parameters
type
required
string
Example: type=series
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (CustomObjectResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a custom object

Authorizations:
BearerAuth
Request Body schema: application/json
required
type_id
required
string [ 1 .. 100 ] characters

The tenant custom_object-class type this record is shaped by (e.g. "series").

name
required
string [ 1 .. 200 ] characters
object

Custom field values keyed by the type's section field IDs.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the custom object's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Request samples

Content type
application/json
{
  • "type_id": "string",
  • "name": "Studies in Modern Poetry",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the custom object's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Replace a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6
Request Body schema: application/json
required
type_id
string [ 1 .. 100 ] characters
name
string [ 1 .. 200 ] characters
schema_version
string [ 1 .. 50 ] characters

Move the record to another version of its type. data is validated against that version. Omitted, the record keeps its version, or takes the latest when type_id changes.

object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the custom object's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Request samples

Content type
application/json
{
  • "type_id": "string",
  • "name": "string",
  • "schema_version": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Partially update a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6
Request Body schema: application/json
required
type_id
string [ 1 .. 100 ] characters
name
string [ 1 .. 200 ] characters
schema_version
string [ 1 .. 50 ] characters

Move the record to another version of its type. data is validated against that version. Omitted, the record keeps its version, or takes the latest when type_id changes.

object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object

self is the custom object's own resource URL, texts the collection of the texts it carries. Further rels may be present; a client follows the ones it knows.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
ReferenceValue (object) or null
required
Array of objects (IdentifierResponse)

The numbers this record carries (ISBN, GTIN, VAT ID, ...). Stored on the record itself; the identifiers sub-resource addresses one entry.

required
Array of objects (PrintedIdentifier)

Read-only. The numbers the record's type marked primary, in the order it declared them — what a picker option, a search row or a detail header shows without resolving the type itself.

Request samples

Content type
application/json
{
  • "type_id": "string",
  • "name": "string",
  • "schema_version": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "primary_identifiers": [
    ],
  • "identifiers": [
    ],
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Files

Issue a presigned upload form for a new file

Validates the request against the file kind named by type — a declaration on the parent's type, or a system kind — enforces cardinality (a cardinality: one kind rejects a second active upload with HTTP 409), and returns a presigned POST form scoped to the caller's tenant prefix in S3.

Some system kinds are written by a service rather than by a person: the generated documents (invoice.document_pdf, invoice.document_xml, offer.document_pdf, stock_dispatch.document_pdf) by the document generator, and email_message.attachment by the inbound-mail worker. Each is written by that one service: a human caller gets 403, and so does a service posting a kind it does not own.

A declared kind is resolved against the parent, so a parent that does not exist in the caller's tenant is 404.

bill.original is the supplier's file a bill records. Replacing it (replaces) is refused with 409 once the bill has left received or has been approved. HEIC photos are refused with 422.

After uploading the bytes via the returned upload form, an S3 event promotes the row from status=pending to ready (or failed).

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (FileParent)

The record a file hangs off. The classes listed here are the file parents the backend accepts; a reference to anything else is rejected with 422.

type
required
string

Either a file kind the parent's type declares — fkd_ followed by 12 hex digits — or a system kind, <parent_class>.<name>. Anything else is rejected with 422 files.unknown_kind.

file_name
required
string
file_size
required
integer >= 1
mime_type
required
string^[\w.+-]+/[\w.+-]+(\s*;.*)?$
description
string or null
language
string or null^[a-z]{2}$

ISO 639-1 language of the content.

content_id
string or null [ 1 .. 250 ] characters ^[\x21-\x7e]+$

The Content-ID of the MIME part an email attachment came from, without angle brackets. Accepted on email_message.attachment only; any other kind answers 422.

ReferenceValue (object) or null

The file this upload takes the place of, for a kind that holds one file. It must hang off the same parent under the same kind. The named row keeps serving downloads until the replacement reaches ready, and is soft-deleted at that moment; a failed upload leaves it alone.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "file"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (FileParent)

The record a file hangs off. The classes listed here are the file parents the backend accepts; a reference to anything else is rejected with 422.

type
required
string
file_name
required
string
file_size
required
integer
mime_type
required
string
sha256
required
string or null

Hex-encoded SHA-256, populated once status=ready.

status
required
string (FileStatus)
Enum: "pending" "ready" "quarantined" "failed" "soft_deleted"

Lifecycle state of a file. pending is set when the upload URL is issued; the S3 ObjectCreated event handler promotes to ready after validation, or to failed/quarantined if validation or malware scanning rejects the object.

retention_class
required
string
Enum: "transient" "standard" "archival"
legal_hold
required
boolean
description
required
string or null
language
required
string or null

ISO 639-1 language of the content.

content_id
required
string or null

The Content-ID of the MIME part an email attachment came from, without angle brackets. Null on every other file.

required
ReferenceValue (object) or null

The file this one replaces while its upload is still in flight; null once the swap completed or when nothing was replaced.

required
object

self is the file's own resource URL; download is the link to the download endpoint.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
required
object (PresignedPost)

S3 presigned-POST form. The client must POST multipart/form-data with every field from fields plus a final file part containing the binary body.

Request samples

Content type
application/json
{
  • "parent": {
    },
  • "type": "fkd_9f3c1a2b4d5e",
  • "file_name": "string",
  • "file_size": 1,
  • "mime_type": "image/png",
  • "description": "string",
  • "language": "de",
  • "content_id": "string",
  • "replaces": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "fil_a1b2c3d4e5f6",
  • "_class": "file",
  • "_name": "Acme Corp",
  • "tenant": {
    },
  • "parent": {
    },
  • "type": "fkd_9f3c1a2b4d5e",
  • "file_name": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "sha256": "string",
  • "status": "pending",
  • "retention_class": "transient",
  • "legal_hold": true,
  • "description": "string",
  • "language": "string",
  • "content_id": "string",
  • "replaces": {
    },
  • "_links": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "upload": {
    }
}

List files attached to a parent entity

Authorizations:
BearerAuth
query Parameters
parent_id
required
string
parent_class
required
string
Enum: "business_partner" "product" "project" "invoice" "offer" "bill" "custom_object" "tenant" "chat_session" "bank_statement" "stock_dispatch" "email_message"
type
string

Filter by namespaced file-type key.

limit
integer <= 200
Default: 50
next_token
string

Responses

Response Schema: application/json
required
Array of objects (FileResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Presigned URLs for the pictures of a page of records

One call for a whole list page: the picture of each named record — the newest ready file of the kind its type marks role: avatar — with a short-lived presigned URL.

A record without a picture is left out of the answer, as is one that does not exist in the caller's tenant: the lookup never leaves the tenant's partition, so a foreign id returns nothing.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
Array of objects (FileDownloadUrlsParent) [ 1 .. 200 ] items

The records whose pictures are wanted. Each entry needs _id and _class; more than 200 is 422.

Responses

Response Schema: application/json
required
Array of objects

One entry per record that has a picture. A record without one — and a record of another tenant — is absent.

Request samples

Content type
application/json
{
  • "parents": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get file metadata

Authorizations:
BearerAuth
path Parameters
file_id
required
string
Example: fil_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "file"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (FileParent)

The record a file hangs off. The classes listed here are the file parents the backend accepts; a reference to anything else is rejected with 422.

type
required
string
file_name
required
string
file_size
required
integer
mime_type
required
string
sha256
required
string or null

Hex-encoded SHA-256, populated once status=ready.

status
required
string (FileStatus)
Enum: "pending" "ready" "quarantined" "failed" "soft_deleted"

Lifecycle state of a file. pending is set when the upload URL is issued; the S3 ObjectCreated event handler promotes to ready after validation, or to failed/quarantined if validation or malware scanning rejects the object.

retention_class
required
string
Enum: "transient" "standard" "archival"
legal_hold
required
boolean
description
required
string or null
language
required
string or null

ISO 639-1 language of the content.

content_id
required
string or null

The Content-ID of the MIME part an email attachment came from, without angle brackets. Null on every other file.

required
ReferenceValue (object) or null

The file this one replaces while its upload is still in flight; null once the swap completed or when nothing was replaced.

required
object

self is the file's own resource URL; download is the link to the download endpoint.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "fil_a1b2c3d4e5f6",
  • "_class": "file",
  • "_name": "Acme Corp",
  • "tenant": {
    },
  • "parent": {
    },
  • "type": "fkd_9f3c1a2b4d5e",
  • "file_name": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "sha256": "string",
  • "status": "pending",
  • "retention_class": "transient",
  • "legal_hold": true,
  • "description": "string",
  • "language": "string",
  • "content_id": "string",
  • "replaces": {
    },
  • "_links": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Soft-delete a file

Sets status=soft_deleted and deleted_at. The S3 object is kept for 30 days then hard-deleted by a nightly cleanup, unless the file carries legal_hold=true.

A bill's original (bill.original) can be deleted only while the bill is received and was never approved; otherwise 409.

Authorizations:
BearerAuth
path Parameters
file_id
required
string
Example: fil_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Issue a short-lived presigned download URL

Authorizations:
BearerAuth
path Parameters
file_id
required
string
query Parameters
disposition
string
Default: "attachment"
Enum: "attachment" "inline"

attachment (default) makes the browser save the file under its name. inline makes it show the file in place, with the stored media type; only a bill's original (bill.original) has one, so the bill's detail page can show it beside the bill. Any other kind is 422.

Responses

Response Schema: application/json
url
required
string <uri>
expires_at
required
integer

Response samples

Content type
application/json
{}

Codelists

List codelists in the catalog (global + tenant)

Authorizations:
BearerAuth
query Parameters
scope
string
Enum: "global" "tenant"
namespace
string
industry
string
authority
string
status
string
Enum: "draft" "active" "deprecated"

Responses

Response Schema: application/json
required
Array of objects (CodelistHeader)
count
required
integer

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0
}

Get a codelist header

Authorizations:
BearerAuth
path Parameters
namespace
required
string

Codelist namespace; may contain slashes (e.g. iso/3166-1). Pass each segment as a separate path segment.

version
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

namespace
required
string
version
required
string
scope
required
string
Enum: "global" "tenant"
status
required
string
Enum: "draft" "active" "deprecated"
required
object
loading
required
string
Enum: "eager" "lazy"
authority
string
industry
Array of strings
object
is_stub
boolean
created_at
integer
updated_at
integer

Response samples

Content type
application/json
{
  • "_id": "cl_iso_3166_1_2020",
  • "_class": "codelist",
  • "_name": "Acme Corp",
  • "namespace": "iso/3166-1",
  • "version": "2020",
  • "authority": "string",
  • "industry": [
    ],
  • "scope": "global",
  • "display_name": {
    },
  • "description": {
    },
  • "loading": "eager",
  • "status": "draft",
  • "is_stub": true,
  • "created_at": 0,
  • "updated_at": 0
}

List codes in a codelist

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
query Parameters
locale
string
Default: "en"

Preferred display language. Never filters which codes are returned; every returned row carries all its translations in display_name, and clients pick their language from there.

parent_code
string
status
string
Enum: "active" "deprecated" "retired"
q
string
limit
integer
Default: 50
offset
integer
Default: 0

Responses

Response Schema: application/json
required
Array of objects (CodeValueResponse)
count
required
integer
total
required
integer

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0,
  • "total": 0
}

Get a single code

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Walk replaced_by_code chain to a terminal node

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string

Responses

Response Schema: application/json
required
object
required
Array of objects (CodeValueResponse)
required
object (CodeValueResponse)

Response samples

Content type
application/json
{
  • "from": {
    },
  • "chain": [
    ],
  • "terminal": {
    }
}

Validate a (namespace, version, code) tuple

Authorizations:
BearerAuth
Request Body schema: application/json
required
namespace
required
string
code
required
string
version
string
Default: "latest"
locale
string
Default: "en"

Preferred language for snapshot.display_snapshot. Never affects whether a code validates: an untranslated code is still valid and falls back to English, with snapshot.snapshot_locale reporting the language actually used.

Responses

Response Schema: application/json
valid
required
boolean
namespace
required
string
version
required
string
code
required
string

Request samples

Content type
application/json
{
  • "namespace": "string",
  • "version": "latest",
  • "code": "string",
  • "locale": "en"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "namespace": "string",
  • "version": "string",
  • "code": "string"
}

Create a tenant codelist (slug becomes part of the namespace)

Authorizations:
BearerAuth
Request Body schema: application/json
required
slug
required
string
required
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

namespace
required
string
version
required
string
scope
required
string
Enum: "global" "tenant"
status
required
string
Enum: "draft" "active" "deprecated"
required
object
loading
required
string
Enum: "eager" "lazy"
authority
string
industry
Array of strings
object
is_stub
boolean
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "slug": "my_categories",
  • "codelist": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "cl_iso_3166_1_2020",
  • "_class": "codelist",
  • "_name": "Acme Corp",
  • "namespace": "iso/3166-1",
  • "version": "2020",
  • "authority": "string",
  • "industry": [
    ],
  • "scope": "global",
  • "display_name": {
    },
  • "description": {
    },
  • "loading": "eager",
  • "status": "draft",
  • "is_stub": true,
  • "created_at": 0,
  • "updated_at": 0
}

Publish a new immutable version of a tenant codelist

Authorizations:
BearerAuth
path Parameters
namespace
required
string

Tenant codelist namespace (must start with tenant:).

Request Body schema: application/json
required
version
required
string
published_at
string <date>
authority
string
industry
Array of strings
object
object
licence
string
attribution
string
status
string
Enum: "draft" "active" "deprecated"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

namespace
required
string
version
required
string
scope
required
string
Enum: "global" "tenant"
status
required
string
Enum: "draft" "active" "deprecated"
required
object
loading
required
string
Enum: "eager" "lazy"
authority
string
industry
Array of strings
object
is_stub
boolean
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "version": "string",
  • "published_at": "2019-08-24",
  • "authority": "string",
  • "industry": [
    ],
  • "display_name": {
    },
  • "description": {
    },
  • "licence": "string",
  • "attribution": "string",
  • "status": "draft"
}

Response samples

Content type
application/json
{
  • "_id": "cl_iso_3166_1_2020",
  • "_class": "codelist",
  • "_name": "Acme Corp",
  • "namespace": "iso/3166-1",
  • "version": "2020",
  • "authority": "string",
  • "industry": [
    ],
  • "scope": "global",
  • "display_name": {
    },
  • "description": {
    },
  • "loading": "eager",
  • "status": "draft",
  • "is_stub": true,
  • "created_at": 0,
  • "updated_at": 0
}

Add a code to a tenant codelist

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
Request Body schema: application/json
required
code
required
string
object
object
parent_code
string
valid_from
string <date>
valid_to
string <date>
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "code": "string",
  • "display_name": {
    },
  • "description": {
    },
  • "parent_code": "string",
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Update a tenant codelist code

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string
Request Body schema: application/json
required
object
object
parent_code
string
valid_from
string <date>
valid_to
string <date>
status
string
Enum: "active" "deprecated" "retired"
replaced_by_code
string
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "display_name": {
    },
  • "description": {
    },
  • "parent_code": "string",
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "status": "active",
  • "replaced_by_code": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a code value (only allowed while the version is unpublished)

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Mark a tenant code as deprecated

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string
Request Body schema: application/json
optional
replaced_by_code
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "replaced_by_code": "string"
}

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Identifiers

List identifiers for a company

Authorizations:
BearerAuth
path Parameters
company_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a company

Authorizations:
BearerAuth
path Parameters
company_id
required
string
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a company identifier

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update a company identifier

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a company identifier

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "applied": true
}

List the tenant's own identifiers

The tenant's VAT ID as Raccoon's customer, with the vies-validator's verdicts. Only the tenant's own id is accepted; any other answers an empty list.

Authorizations:
BearerAuth
path Parameters
tenant_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to the tenant

For the tenant's owner. Not available to the agent: it is the tenant's detail as Raccoon's customer. Only vat_eu is accepted, and only one (a second is a 409). The vies-validator checks it off the request path.

Authorizations:
BearerAuth
path Parameters
tenant_id
required
string
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get one of the tenant's identifiers

Authorizations:
BearerAuth
path Parameters
tenant_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Change one of the tenant's identifiers

Changing the value drops its validations.

Authorizations:
BearerAuth
path Parameters
tenant_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Remove one of the tenant's identifiers

Authorizations:
BearerAuth
path Parameters
tenant_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to a tenant identifier (vies-validator callback)

Service-only: a forged verdict would be a reverse charge Raccoon never checked. On every other parent an administrator may call it.

Authorizations:
BearerAuth
path Parameters
tenant_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "applied": true
}

Cross-entity reverse lookup by identifier value

Returns all identifier records matching the given schema_key and value within the authenticated tenant. Each result contains a parent Reference pointing to the owning entity. Use the nested sub-resource endpoints for CRUD operations on identifiers.

Authorizations:
BearerAuth
query Parameters
schema_key
required
string
Example: schema_key=ean13
identifier
required
string
Example: identifier=4006381333931

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Identifier schemas selectable for an entity class

Returns the platform identifier schemas that can be attached to the given entity class. Every scheme is returned (a company may hold a foreign VAT registration, so none are hidden); when country is supplied the scheme issued by that country (e.g. vat_eu for an EU company, vat_gb for a UK company) is sorted first and flagged recommended. Drives the add-identifier dropdown on the Company form.

Authorizations:
BearerAuth
query Parameters
entity_class
required
string
Example: entity_class=company
country
string
Example: country=DE

ISO 3166-1 alpha-2 code of the entity's home country.

Responses

Response Schema: application/json
required
Array of objects (IdentifierSchema)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

List identifiers for a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a product identifier

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update a product identifier

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a product identifier

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "applied": true
}

List identifiers for a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a business partner identifier

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update a business partner identifier

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a business partner identifier

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Dedicated write path for async validators (e.g. the VIES worker) to report a verdict, kept off the general identifier PATCH so a worker write and a concurrent user value-edit can't clobber each other. Applies staleness + never-downgrade rules; applied=false when skipped.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "applied": true
}

List identifiers for an invoice

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to an invoice

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get an invoice identifier

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update an invoice identifier

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete an invoice identifier

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "applied": true
}

List identifiers for a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a project identifier

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update a project identifier

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a project identifier

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "applied": true
}

List identifiers for a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Request Body schema: application/json
required
Any of
key
required
string

Key of the type's identifier declaration this value belongs to.

value
required
string
schema_key
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "gtin",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Get a custom-object identifier

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Update a custom-object identifier

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string or null

Key of the type's identifier declaration this value was entered under. It survives a rename of the declaration, and tells two declarations of one scheme apart. Null on a parent without a type (a company).

schema_key
required
string

The registry scheme the value is validated against, taken from the declaration.

value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
Array of objects (IdentifierWarning)

A failed format check on a scheme that warns instead of refusing the save (leitweg_id, peppol_id, datev_account). Computed on every read, never stored. Empty when the value passes or the scheme has no such check.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "key": "idd_9f2c81a4bd10",
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "warnings": [
    ],
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a custom-object identifier

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Texts

List the texts a product carries

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
query Parameters
next_token
string

Responses

Response Schema: application/json
required
Array of objects (TextResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Write a product's text of one kind

Upsert. Answers 200 with the stored row, or 204 when the value held nothing in any language — that deletes the row, the same as DELETE.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Request Body schema: application/json
required
required
object

The text per language, keyed by ISO 639-1 code.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string
required
object

The text per language, keyed by ISO 639-1 code.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6.tkd_0a1b2c3d4e5f",
  • "_class": "text",
  • "_links": {
    },
  • "tenant": {
    },
  • "parent": {
    },
  • "key": "tkd_0a1b2c3d4e5f",
  • "value": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a product's text of one kind

Authorizations:
BearerAuth
path Parameters
product_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List the texts a project carries

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6
query Parameters
next_token
string

Responses

Response Schema: application/json
required
Array of objects (TextResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Write a project's text of one kind

Upsert. Answers 200 with the stored row, or 204 when the value held nothing in any language — that deletes the row, the same as DELETE.

Authorizations:
BearerAuth
path Parameters
project_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Request Body schema: application/json
required
required
object

The text per language, keyed by ISO 639-1 code.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string
required
object

The text per language, keyed by ISO 639-1 code.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6.tkd_0a1b2c3d4e5f",
  • "_class": "text",
  • "_links": {
    },
  • "tenant": {
    },
  • "parent": {
    },
  • "key": "tkd_0a1b2c3d4e5f",
  • "value": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a project's text of one kind

Authorizations:
BearerAuth
path Parameters
project_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List the texts a custom object carries

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6
query Parameters
next_token
string

Responses

Response Schema: application/json
required
Array of objects (TextResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Write a custom object's text of one kind

Upsert. Answers 200 with the stored row, or 204 when the value held nothing in any language — that deletes the row, the same as DELETE.

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Request Body schema: application/json
required
required
object

The text per language, keyed by ISO 639-1 code.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string
required
object

The text per language, keyed by ISO 639-1 code.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6.tkd_0a1b2c3d4e5f",
  • "_class": "text",
  • "_links": {
    },
  • "tenant": {
    },
  • "parent": {
    },
  • "key": "tkd_0a1b2c3d4e5f",
  • "value": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a custom object's text of one kind

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

List the texts a business partner carries

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
query Parameters
next_token
string

Responses

Response Schema: application/json
required
Array of objects (TextResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Write a business partner's text of one kind

Upsert. Answers 200 with the stored row, or 204 when the value held nothing in any language — that deletes the row, the same as DELETE.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Request Body schema: application/json
required
required
object

The text per language, keyed by ISO 639-1 code.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

key
required
string
required
object

The text per language, keyed by ISO 639-1 code.

created_at
required
integer
updated_at
required
integer
required
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6.tkd_0a1b2c3d4e5f",
  • "_class": "text",
  • "_links": {
    },
  • "tenant": {
    },
  • "parent": {
    },
  • "key": "tkd_0a1b2c3d4e5f",
  • "value": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Delete a business partner's text of one kind

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
text_kind_key
required
string
Example: tkd_0a1b2c3d4e5f

The tkd_ declaration key of the text kind.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Billing

This tenant's subscription

What plan the tenant is on and what state it is in, together with the price actually being charged.

The price is resolved from the subscription's stored pricing region, never from where the caller is — a tenant keeps the pricing of the market it signed up in.

Never 404s: a tenant with no stored subscription is created on the free plan on first read, so no client has to handle a billing-not-set-up state.

Status changes are consequences of payment-provider events and arrive on their own endpoints; there is no route by which a tenant can put itself on a paid plan.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
subscription_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

Reference into the published plan catalogue; _id is the plan key served by GET /resource/v1/billing-plans.

plan_name
required
string
status
required
string
Enum: "free" "active" "past_due" "grace" "canceled"

past_due keeps the paid plan's limits — a failed card is not a cancelled customer. grace drops to the free tier's limits without deleting anything. canceled keeps paid limits until current_period_end.

region_key
required
string
currency
required
string = 3 characters
band
required
string
Enum: "a" "b" "c" "d"
required
MonetaryAmount (object) or null

Null on the free plan.

tax_display
required
string or null
Enum: "gross" "net" null
entitlements_active
required
boolean

Whether the subscribed plan's limits apply (active/past_due) or the free tier's do. Computed server-side so no client re-implements the rule.

required
object (ProviderCapabilities)

What this tenant's payment rail can actually do — static facts, not state.

A rail without hosted checkout or auto-renew needs a visibly different upgrade flow, and the client reads that from here rather than inferring it from provider_key. A tenant with no provider yet (everyone on the free tier) is answered with the stage's configured provider, so the billing page can render an upgrade path before any provider id exists.

provider_key
required
string or null
Enum: "stub" "stripe" null
provider_customer_id
required
string or null
provider_subscription_id
required
string or null
current_period_start
required
integer or null
current_period_end
required
integer or null
cancel_at_period_end
required
boolean
required
Reference (object) or null

The lower plan this subscription changes to at current_period_end, or null when no downgrade is scheduled. Written with PATCH /resource/v1/subscriptions/current.

past_due_since
required
integer or null

When the current run of failed payments began. Set on entering past_due, kept through grace, cleared when the tenant recovers or the plan ends. The move to grace is measured from it.

last_provider_event_at
required
integer or null

The provider's own timestamp for the most recent event applied. Events older than this are rejected, because webhook delivery is unordered.

ReferenceValue (object) or null

Null when the subscription was created by self-service registration, where the acting user is not yet established.

Response samples

Content type
application/json
{
  • "subscription_id": "sub_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "status": "free",
  • "region_key": "ke",
  • "currency": "str",
  • "band": "a",
  • "price": {
    },
  • "tax_display": "gross",
  • "entitlements_active": true,
  • "provider_capabilities": {
    },
  • "provider_key": "stub",
  • "provider_customer_id": "string",
  • "provider_subscription_id": "string",
  • "current_period_start": 0,
  • "current_period_end": 0,
  • "cancel_at_period_end": true,
  • "scheduled_plan": {
    },
  • "past_due_since": 0,
  • "last_provider_event_at": 0
}

Decide what happens when the period ends (owner)

cancel_at_period_end and scheduled_plan are the only fields a tenant may write, one per request. Both say what should happen when the current period ends, and neither touches status nor plan.

Setting it true is the "Cancel plan" path: the plan runs to the end of the period the tenant already paid for, nothing is taken away today, and asking twice is the same as asking once. Refused on the free plan, which has nothing to cancel.

Setting it true also drops a scheduled downgrade: a plan that ends does not change first.

Setting it false is the "Keep plan" path, available any time before the period actually ends. A 422 when no cancellation is pending, which is the honest answer: there is nothing to undo, and succeeding quietly would let a client report "resumed" for a plan nobody had stopped.

scheduled_plan: {"_id": "<plan_key>"} moves to a lower paid plan (for example Growth → Starter) at current_period_end. Nothing is charged or refunded now and the current plan's limits stay until then — no proration. Setting the same plan again changes nothing; another lower plan replaces it. scheduled_plan: null keeps the current plan and is a no-op when nothing is scheduled. Moving to Free is a cancellation, not a downgrade (422); a plan that is not lower or is unknown is a 422; a subscription that is not active, a pending cancellation, a period granted by hand that is waiting to start, a current period whose end was set by hand, or a period that has already ended and is not renewed yet is a 409.

A change that lost to another one made meanwhile (a downgrade and a cancellation, or two downgrades) is a 409 with details.retryable true; reading the subscription again and retrying gets past it.

Owner-gated, like checkout: an administrator can read the bill, only an owner can stop it.

Authorizations:
BearerAuth
Request Body schema: application/json
required
= 1 properties
cancel_at_period_end
boolean
Reference (object) or null

A lower paid plan (_id is the plan key) to move to at current_period_end; null keeps the current plan.

Responses

Response Schema: application/json
subscription_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

Reference into the published plan catalogue; _id is the plan key served by GET /resource/v1/billing-plans.

plan_name
required
string
status
required
string
Enum: "free" "active" "past_due" "grace" "canceled"

past_due keeps the paid plan's limits — a failed card is not a cancelled customer. grace drops to the free tier's limits without deleting anything. canceled keeps paid limits until current_period_end.

region_key
required
string
currency
required
string = 3 characters
band
required
string
Enum: "a" "b" "c" "d"
required
MonetaryAmount (object) or null

Null on the free plan.

tax_display
required
string or null
Enum: "gross" "net" null
entitlements_active
required
boolean

Whether the subscribed plan's limits apply (active/past_due) or the free tier's do. Computed server-side so no client re-implements the rule.

required
object (ProviderCapabilities)

What this tenant's payment rail can actually do — static facts, not state.

A rail without hosted checkout or auto-renew needs a visibly different upgrade flow, and the client reads that from here rather than inferring it from provider_key. A tenant with no provider yet (everyone on the free tier) is answered with the stage's configured provider, so the billing page can render an upgrade path before any provider id exists.

provider_key
required
string or null
Enum: "stub" "stripe" null
provider_customer_id
required
string or null
provider_subscription_id
required
string or null
current_period_start
required
integer or null
current_period_end
required
integer or null
cancel_at_period_end
required
boolean
required
Reference (object) or null

The lower plan this subscription changes to at current_period_end, or null when no downgrade is scheduled. Written with PATCH /resource/v1/subscriptions/current.

past_due_since
required
integer or null

When the current run of failed payments began. Set on entering past_due, kept through grace, cleared when the tenant recovers or the plan ends. The move to grace is measured from it.

last_provider_event_at
required
integer or null

The provider's own timestamp for the most recent event applied. Events older than this are rejected, because webhook delivery is unordered.

ReferenceValue (object) or null

Null when the subscription was created by self-service registration, where the acting user is not yet established.

Request samples

Content type
application/json
{
  • "cancel_at_period_end": true
}

Response samples

Content type
application/json
{
  • "subscription_id": "sub_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "status": "free",
  • "region_key": "ke",
  • "currency": "str",
  • "band": "a",
  • "price": {
    },
  • "tax_display": "gross",
  • "entitlements_active": true,
  • "provider_capabilities": {
    },
  • "provider_key": "stub",
  • "provider_customer_id": "string",
  • "provider_subscription_id": "string",
  • "current_period_start": 0,
  • "current_period_end": 0,
  • "cancel_at_period_end": true,
  • "scheduled_plan": {
    },
  • "past_due_since": 0,
  • "last_provider_event_at": 0
}

This tenant's usage against its plan allowance

What the tenant has consumed inside the period it is currently paying for, with the plan's limit beside each meter.

The period follows the subscription, not the calendar: on a paid plan it is the billing anniversary window, on the free plan it is the calendar month. Clients render resets_at and never need to know which rule applied.

Every metric the plan defines is returned, including untouched ones at zero — an absent meter would read as a missing feature rather than an unused one.

Raccoon's own token costs are deliberately absent. The plan bundles a number of agent actions, not a number of tokens.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
period
required
string

Opaque key for the window being metered. Follows the subscription's billing anniversary on a paid plan and the calendar month on free — clients display resets_at rather than parsing this.

resets_at
required
integer

Unix seconds at which these counters reset — the billing anniversary on a paid plan, the month boundary on free. One date, whichever rule produced it.

required
Array of objects (UsageMetric)
warnings
required
Array of strings

Metrics at or above 80% of their limit.

Response samples

Content type
application/json
{
  • "period": "sub#1755302400",
  • "resets_at": 0,
  • "metrics": [
    ],
  • "warnings": [
    ]
}

Start paying for a plan

Opens a checkout attempt and answers 202: nothing has been paid and nothing decided yet. The provider reports the outcome asynchronously, and the client follows the intent rather than awaiting a reply.

The plan, price and tax display are snapshotted onto the intent, so a catalogue edit between the price the tenant read and the charge the provider makes cannot change what they agreed to. The pricing region comes from the tenant's subscription — frozen at registration — never from the request.

Every plan change that costs money is a checkout intent:

  • a tenant not being billed (free, canceled) buys any paid plan;
  • an active tenant buys a higher plan — an upgrade, which takes effect once paid, starts a new billing period (the anniversary resets) and grants the new plan's full allowance at once;
  • a past_due or grace tenant buys its current plan — "Pay now", which returns it to active in the period it already holds.

A lower plan is not checked out: it is scheduled_plan on PATCH /resource/v1/subscriptions/current. Nothing is prorated.

Owner-gated: this is the call that commits the tenant to money.

Authorizations:
BearerAuth
Request Body schema: application/json
required
plan_key
required
string

A paid catalogue plan. free is refused; downgrading is a cancel.

stub_behaviour
string or null
Enum: "complete" "payment_failed" "canceled" "expire" "lapse" null

Simulate an outcome. 422 unless the stage's provider is the stub. expire leaves a session open until its window ends; lapse creates the intent already past expires_at, so the sweeper expires it at once while its session window still blocks a new checkout.

Responses

Request samples

Content type
application/json
{
  • "plan_key": "starter",
  • "stub_behaviour": "complete"
}

Response samples

Content type
application/json
{
  • "checkout_intent_id": "chk_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "region_key": "ke",
  • "price": {
    },
  • "tax_display": "gross",
  • "status": "pending",
  • "provider_key": "stub",
  • "provider_session_id": "string",
  • "provider_session_url": "string",
  • "provider_session_expires_at": 0,
  • "stub_behaviour": "complete",
  • "expires_at": 0,
  • "resolved_at": 0,
  • "failure_reason": "string"
}

This tenant's checkout attempts

Including the failed ones. Retrying creates a new intent rather than overwriting the old, so "my payment did not work" has evidence attached to it.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (CheckoutIntent)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

One checkout attempt

An intent past its expires_at reads as expired whatever is stored, so a lapsed checkout never looks live merely because the sweeper has not reached it yet.

Authorizations:
BearerAuth
path Parameters
checkout_intent_id
required
string
Example: chk_9f2c1a04b7e3

Responses

Response Schema: application/json
checkout_intent_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The plan being bought, snapshotted at create.

plan_name
required
string
region_key
required
string

The tenant's frozen pricing region, so a checkout cannot be quoted in a cheaper market than the tenant belongs to.

required
MonetaryAmount (object) or null

What the tenant agreed to pay, snapshotted at create.

tax_display
required
string or null
Enum: "gross" "net" null
status
required
string
Enum: "pending" "awaiting_payment" "completed" "payment_failed" "canceled" "expired"

pending — created, provider not yet engaged. awaiting_payment — the provider has a session open and is waiting on the payer. completed, payment_failed, canceled and expired are terminal; retrying means creating a new intent, which keeps the failed attempt readable instead of overwriting the evidence.

provider_key
required
string
Enum: "stub" "stripe"

Stamped from per-stage config, never from the request.

provider_session_id
required
string or null
provider_session_url
required
string or null

Where to send the payer, on a rail with hosted checkout. Null on a rail without one — see provider_capabilities.supports_hosted_checkout.

provider_session_expires_at
required
integer or null

Unix seconds after which the provider session can no longer take money. Null until the provider reports a session. It can lie past expires_at (a Stripe session lives at least 30 minutes), and while it is in the future a new checkout is refused unless this intent is completed or canceled. When the provider closes the session early it moves to the moment of closing.

stub_behaviour
required
string or null
Enum: "complete" "payment_failed" "canceled" "expire" "lapse" null

Which outcome the stub should simulate. Accepted only when the stage's provider is the stub; a real rail decides its own outcome, and letting a request name one would be a way to fake a payment.

expires_at
required
integer

Unix seconds after which the intent is no longer live.

resolved_at
required
integer or null
failure_reason
required
string or null
ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "checkout_intent_id": "chk_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "region_key": "ke",
  • "price": {
    },
  • "tax_display": "gross",
  • "status": "pending",
  • "provider_key": "stub",
  • "provider_session_id": "string",
  • "provider_session_url": "string",
  • "provider_session_expires_at": 0,
  • "stub_behaviour": "complete",
  • "expires_at": 0,
  • "resolved_at": 0,
  • "failure_reason": "string"
}

Provider callback — a payment session is open

The provider reporting that it has a session open and is waiting for the payer, moving the intent to awaiting_payment.

Separate from the outcome callback because a rail with hosted checkout needs somewhere to put the URL to send the payer to, and the client has to tell "not started" apart from "waiting on the payer".

Service-gated. Callable only by a registered billing-provider service or a superuser — deliberately stricter than the validator callbacks, which admit any admin. A forged call here is money, not provenance.

Authorizations:
BearerAuth
path Parameters
checkout_intent_id
required
string
Request Body schema: application/json
required
provider_session_id
required
string
provider_session_url
string or null

Where to send the payer, on a rail with hosted checkout.

provider_session_expires_at
integer or null

Unix seconds after which the session can no longer take money. A new checkout for the tenant is refused until then.

Responses

Response Schema: application/json
checkout_intent_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The plan being bought, snapshotted at create.

plan_name
required
string
region_key
required
string

The tenant's frozen pricing region, so a checkout cannot be quoted in a cheaper market than the tenant belongs to.

required
MonetaryAmount (object) or null

What the tenant agreed to pay, snapshotted at create.

tax_display
required
string or null
Enum: "gross" "net" null
status
required
string
Enum: "pending" "awaiting_payment" "completed" "payment_failed" "canceled" "expired"

pending — created, provider not yet engaged. awaiting_payment — the provider has a session open and is waiting on the payer. completed, payment_failed, canceled and expired are terminal; retrying means creating a new intent, which keeps the failed attempt readable instead of overwriting the evidence.

provider_key
required
string
Enum: "stub" "stripe"

Stamped from per-stage config, never from the request.

provider_session_id
required
string or null
provider_session_url
required
string or null

Where to send the payer, on a rail with hosted checkout. Null on a rail without one — see provider_capabilities.supports_hosted_checkout.

provider_session_expires_at
required
integer or null

Unix seconds after which the provider session can no longer take money. Null until the provider reports a session. It can lie past expires_at (a Stripe session lives at least 30 minutes), and while it is in the future a new checkout is refused unless this intent is completed or canceled. When the provider closes the session early it moves to the moment of closing.

stub_behaviour
required
string or null
Enum: "complete" "payment_failed" "canceled" "expire" "lapse" null

Which outcome the stub should simulate. Accepted only when the stage's provider is the stub; a real rail decides its own outcome, and letting a request name one would be a way to fake a payment.

expires_at
required
integer

Unix seconds after which the intent is no longer live.

resolved_at
required
integer or null
failure_reason
required
string or null
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "provider_session_id": "string",
  • "provider_session_url": "string",
  • "provider_session_expires_at": 0
}

Response samples

Content type
application/json
{
  • "checkout_intent_id": "chk_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "region_key": "ke",
  • "price": {
    },
  • "tax_display": "gross",
  • "status": "pending",
  • "provider_key": "stub",
  • "provider_session_id": "string",
  • "provider_session_url": "string",
  • "provider_session_expires_at": 0,
  • "stub_behaviour": "complete",
  • "expires_at": 0,
  • "resolved_at": 0,
  • "failure_reason": "string"
}

Provider callback — the payment session was closed

The provider reporting that it closed the session, so it can no longer take money. Sets provider_session_expires_at to closed_at, which lets the tenant start a new checkout. The intent's status does not change. A repeat, or a closed_at later than the stored value, changes nothing.

Service-gated, like the other provider callbacks.

Authorizations:
BearerAuth
path Parameters
checkout_intent_id
required
string
Request Body schema: application/json
required
closed_at
required
integer

Unix seconds at which the provider closed the session.

Responses

Response Schema: application/json
checkout_intent_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The plan being bought, snapshotted at create.

plan_name
required
string
region_key
required
string

The tenant's frozen pricing region, so a checkout cannot be quoted in a cheaper market than the tenant belongs to.

required
MonetaryAmount (object) or null

What the tenant agreed to pay, snapshotted at create.

tax_display
required
string or null
Enum: "gross" "net" null
status
required
string
Enum: "pending" "awaiting_payment" "completed" "payment_failed" "canceled" "expired"

pending — created, provider not yet engaged. awaiting_payment — the provider has a session open and is waiting on the payer. completed, payment_failed, canceled and expired are terminal; retrying means creating a new intent, which keeps the failed attempt readable instead of overwriting the evidence.

provider_key
required
string
Enum: "stub" "stripe"

Stamped from per-stage config, never from the request.

provider_session_id
required
string or null
provider_session_url
required
string or null

Where to send the payer, on a rail with hosted checkout. Null on a rail without one — see provider_capabilities.supports_hosted_checkout.

provider_session_expires_at
required
integer or null

Unix seconds after which the provider session can no longer take money. Null until the provider reports a session. It can lie past expires_at (a Stripe session lives at least 30 minutes), and while it is in the future a new checkout is refused unless this intent is completed or canceled. When the provider closes the session early it moves to the moment of closing.

stub_behaviour
required
string or null
Enum: "complete" "payment_failed" "canceled" "expire" "lapse" null

Which outcome the stub should simulate. Accepted only when the stage's provider is the stub; a real rail decides its own outcome, and letting a request name one would be a way to fake a payment.

expires_at
required
integer

Unix seconds after which the intent is no longer live.

resolved_at
required
integer or null
failure_reason
required
string or null
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "closed_at": 0
}

Response samples

Content type
application/json
{
  • "checkout_intent_id": "chk_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "region_key": "ke",
  • "price": {
    },
  • "tax_display": "gross",
  • "status": "pending",
  • "provider_key": "stub",
  • "provider_session_id": "string",
  • "provider_session_url": "string",
  • "provider_session_expires_at": 0,
  • "stub_behaviour": "complete",
  • "expires_at": 0,
  • "resolved_at": 0,
  • "failure_reason": "string"
}

Provider callback — a checkout outcome

The provider reporting what happened. Resolves the intent and moves the subscription with it, through the same settlement path the in-core stub drives — which is what makes "one FSM for every provider" structural rather than a convention.

A repeat of the state the intent is already in is accepted and changes nothing: provider delivery is at-least-once, and answering 409 to a retry would make every duplicate look like a failure. On checkout_completed the intent is marked completed only after the subscription has moved and the plan period is granted, so a completed intent means the whole settlement landed.

A 409 whose details.retryable is true (the subscription changed meanwhile, or the event is older than the last one applied) changes nothing and may succeed when sent again with a fresh read.

Service-gated, for the same reason as the session callback: a forged checkout_completed grants a paid plan.

Authorizations:
BearerAuth
path Parameters
checkout_intent_id
required
string
Request Body schema: application/json
required
event
required
string
Enum: "checkout_completed" "payment_succeeded" "payment_failed" "subscription_updated" "subscription_ended" "checkout_canceled" "checkout_expired"
occurred_at
integer or null

The provider's clock, not ours. The subscription's staleness guard compares against it, so substituting our own would make an out-of-order redelivery look current and let a retried "payment failed" undo the recovery that fixed it.

failure_reason
string or null
provider_customer_id
string or null
provider_subscription_id
string or null
current_period_start
integer or null

Start of the provider's billing period, unix seconds. With current_period_end, a new plan's anchor follows the provider's instead of our clock.

current_period_end
integer or null

End of the provider's billing period, unix seconds.

Responses

Response Schema: application/json
checkout_intent_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The plan being bought, snapshotted at create.

plan_name
required
string
region_key
required
string

The tenant's frozen pricing region, so a checkout cannot be quoted in a cheaper market than the tenant belongs to.

required
MonetaryAmount (object) or null

What the tenant agreed to pay, snapshotted at create.

tax_display
required
string or null
Enum: "gross" "net" null
status
required
string
Enum: "pending" "awaiting_payment" "completed" "payment_failed" "canceled" "expired"

pending — created, provider not yet engaged. awaiting_payment — the provider has a session open and is waiting on the payer. completed, payment_failed, canceled and expired are terminal; retrying means creating a new intent, which keeps the failed attempt readable instead of overwriting the evidence.

provider_key
required
string
Enum: "stub" "stripe"

Stamped from per-stage config, never from the request.

provider_session_id
required
string or null
provider_session_url
required
string or null

Where to send the payer, on a rail with hosted checkout. Null on a rail without one — see provider_capabilities.supports_hosted_checkout.

provider_session_expires_at
required
integer or null

Unix seconds after which the provider session can no longer take money. Null until the provider reports a session. It can lie past expires_at (a Stripe session lives at least 30 minutes), and while it is in the future a new checkout is refused unless this intent is completed or canceled. When the provider closes the session early it moves to the moment of closing.

stub_behaviour
required
string or null
Enum: "complete" "payment_failed" "canceled" "expire" "lapse" null

Which outcome the stub should simulate. Accepted only when the stage's provider is the stub; a real rail decides its own outcome, and letting a request name one would be a way to fake a payment.

expires_at
required
integer

Unix seconds after which the intent is no longer live.

resolved_at
required
integer or null
failure_reason
required
string or null
ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "event": "checkout_completed",
  • "occurred_at": 0,
  • "failure_reason": "string",
  • "provider_customer_id": "string",
  • "provider_subscription_id": "string",
  • "current_period_start": 0,
  • "current_period_end": 0
}

Response samples

Content type
application/json
{
  • "checkout_intent_id": "chk_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "region_key": "ke",
  • "price": {
    },
  • "tax_display": "gross",
  • "status": "pending",
  • "provider_key": "stub",
  • "provider_session_id": "string",
  • "provider_session_url": "string",
  • "provider_session_expires_at": 0,
  • "stub_behaviour": "complete",
  • "expires_at": 0,
  • "resolved_at": 0,
  • "failure_reason": "string"
}

Provider callback — a fact about a running subscription

The provider reporting a renewal, a failed renewal, an ending or a change to a subscription it already runs. These have no checkout intent, so they do not go through the intent's callback.

payment_succeeded moves the subscription to active, payment_failed to past_due, subscription_ended to canceled, and subscription_updated keeps the status. Each may carry the provider's current_period_start/current_period_end, which is how a renewal advances the billing window. No plan period is granted here.

Answers 409, and changes nothing, when the move is illegal, the event is older than the last one applied, the tenant is on the free plan (only a settled checkout grants a plan), or provider_subscription_id is not the one on file. Checkout outcomes are a 422. The 409 carries details.retryable: true when the subscription changed meanwhile or the event is older than the last one applied: a fresh read of the provider can get past those, the others are final.

Service-gated, like the checkout callbacks: a forged renewal keeps a tenant on a plan nobody paid for.

Authorizations:
BearerAuth
Request Body schema: application/json
required
event
required
string
Enum: "payment_succeeded" "payment_failed" "subscription_updated" "subscription_ended"
provider_subscription_id
required
string

Which of the provider's subscriptions this is about. Must be the one on file, so a late event about an old subscription cannot move the new one.

occurred_at
integer or null

When the reported state held, as unix seconds. Compared against the last applied event; an older one is refused.

current_period_start
integer or null

Start of the provider's current billing period, unix seconds.

current_period_end
integer or null

End of the provider's current billing period, unix seconds.

Responses

Response Schema: application/json
subscription_id
required
string
tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

Reference into the published plan catalogue; _id is the plan key served by GET /resource/v1/billing-plans.

plan_name
required
string
status
required
string
Enum: "free" "active" "past_due" "grace" "canceled"

past_due keeps the paid plan's limits — a failed card is not a cancelled customer. grace drops to the free tier's limits without deleting anything. canceled keeps paid limits until current_period_end.

region_key
required
string
currency
required
string = 3 characters
band
required
string
Enum: "a" "b" "c" "d"
required
MonetaryAmount (object) or null

Null on the free plan.

tax_display
required
string or null
Enum: "gross" "net" null
entitlements_active
required
boolean

Whether the subscribed plan's limits apply (active/past_due) or the free tier's do. Computed server-side so no client re-implements the rule.

required
object (ProviderCapabilities)

What this tenant's payment rail can actually do — static facts, not state.

A rail without hosted checkout or auto-renew needs a visibly different upgrade flow, and the client reads that from here rather than inferring it from provider_key. A tenant with no provider yet (everyone on the free tier) is answered with the stage's configured provider, so the billing page can render an upgrade path before any provider id exists.

provider_key
required
string or null
Enum: "stub" "stripe" null
provider_customer_id
required
string or null
provider_subscription_id
required
string or null
current_period_start
required
integer or null
current_period_end
required
integer or null
cancel_at_period_end
required
boolean
required
Reference (object) or null

The lower plan this subscription changes to at current_period_end, or null when no downgrade is scheduled. Written with PATCH /resource/v1/subscriptions/current.

past_due_since
required
integer or null

When the current run of failed payments began. Set on entering past_due, kept through grace, cleared when the tenant recovers or the plan ends. The move to grace is measured from it.

last_provider_event_at
required
integer or null

The provider's own timestamp for the most recent event applied. Events older than this are rejected, because webhook delivery is unordered.

ReferenceValue (object) or null

Null when the subscription was created by self-service registration, where the acting user is not yet established.

Request samples

Content type
application/json
{
  • "event": "payment_succeeded",
  • "provider_subscription_id": "string",
  • "occurred_at": 0,
  • "current_period_start": 0,
  • "current_period_end": 0
}

Response samples

Content type
application/json
{
  • "subscription_id": "sub_9f2c1a04b7e3",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "status": "free",
  • "region_key": "ke",
  • "currency": "str",
  • "band": "a",
  • "price": {
    },
  • "tax_display": "gross",
  • "entitlements_active": true,
  • "provider_capabilities": {
    },
  • "provider_key": "stub",
  • "provider_customer_id": "string",
  • "provider_subscription_id": "string",
  • "current_period_start": 0,
  • "current_period_end": 0,
  • "cancel_at_period_end": true,
  • "scheduled_plan": {
    },
  • "past_due_since": 0,
  • "last_provider_event_at": 0
}

This tenant's plan history

Every plan period this tenant has been on, oldest first.

A plan change closes one period and opens the next, so these rows are the audit trail rather than a reconstruction of one — nothing is edited in place and nothing is lost.

Each period carries the allowances that were granted with it, frozen at the moment it opened. A later catalogue change cannot reach them, which is what makes grandfathering automatic; a custom period may carry numbers the catalogue never offered at all.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
required
Array of objects (SubscriptionPeriod)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

The billing periods this tenant has paid for

One row per billing period a payment provider charged, oldest first. Raccoon invoices the tenant from these rows.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
required
Array of objects (SubscriptionCharge)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Report a paid billing period (provider callback)

A payment provider reporting that it charged the tenant for one billing period: Stripe on invoice.paid. The plan and price are taken from the plan period in force at period_start.

Idempotent per billing period: a second report for the same period_start returns the charge already recorded and changes nothing.

A 409 with details.retryable: true while the tenant is still free or no paid plan period covers period_start: the checkout that grants it may not have settled yet. A final 409 when the payment is for another provider subscription, or when the period's plan had no catalogue price for the region. A 422 when amount_paid is not in the subscription's currency.

Service-gated: a forged charge is what Raccoon would invoice and book as paid.

Authorizations:
BearerAuth
Request Body schema: application/json
required
provider_subscription_id
required
string non-empty

Must be the provider subscription on file; any other is a 409.

period_start
required
integer

Unix seconds; the start of the billing period paid for.

period_end
required
integer

Unix seconds; must be after period_start.

required
object (MonetaryAmountInput)

Request-side counterpart of MonetaryAmount. Identical, except that amount also accepts a quoted decimal string — the encoding the precision contract above tells clients to use for sub-cent values, which the server's Pydantic coerces to an exact Decimal.

Responses always carry amount as a JSON number; use MonetaryAmount for those.

paid_at
integer or null

Unix seconds. Defaults to the time of the report.

provider_invoice_id
string or null [ 1 .. 255 ] characters

Responses

Response Schema: application/json
subscription_charge_id
required
string

Derived from period_start, so one billing period has one charge.

tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The catalogue plan of the period, _id the plan key.

plan_name
required
string
required
object

The plan period the price was taken from.

region_key
required
string
period_start
required
integer

Unix seconds; inclusive.

period_end
required
integer

Unix seconds; exclusive.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

tax_display
required
string
Enum: "gross" "net"

Whether price includes VAT, from the catalogue row the period was priced from.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

paid_at
required
integer

Unix seconds.

provider_key
required
string
Enum: "stub" "stripe"
provider_subscription_id
required
string
provider_invoice_id
required
string or null

The provider's own invoice for the payment, such as a Stripe in_… id.

required
Reference (object) or null

Raccoon's own invoice for the charge, issued from the system tenant. Null until it is issued.

ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "provider_subscription_id": "string",
  • "period_start": 0,
  • "period_end": 0,
  • "amount_paid": {
    },
  • "paid_at": 0,
  • "provider_invoice_id": "string"
}

Response samples

Content type
application/json
{
  • "subscription_charge_id": "subc_1793404800",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "subscription_period": {
    },
  • "region_key": "ke",
  • "period_start": 0,
  • "period_end": 0,
  • "price": {
    },
  • "tax_display": "gross",
  • "amount_paid": {
    },
  • "paid_at": 0,
  • "provider_key": "stub",
  • "provider_subscription_id": "string",
  • "provider_invoice_id": "string",
  • "invoice": {
    }
}

One billing period this tenant has paid for

Authorizations:
BearerAuth
path Parameters
subscription_charge_id
required
string

Responses

Response Schema: application/json
subscription_charge_id
required
string

Derived from period_start, so one billing period has one charge.

tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The catalogue plan of the period, _id the plan key.

plan_name
required
string
required
object

The plan period the price was taken from.

region_key
required
string
period_start
required
integer

Unix seconds; inclusive.

period_end
required
integer

Unix seconds; exclusive.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

tax_display
required
string
Enum: "gross" "net"

Whether price includes VAT, from the catalogue row the period was priced from.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

paid_at
required
integer

Unix seconds.

provider_key
required
string
Enum: "stub" "stripe"
provider_subscription_id
required
string
provider_invoice_id
required
string or null

The provider's own invoice for the payment, such as a Stripe in_… id.

required
Reference (object) or null

Raccoon's own invoice for the charge, issued from the system tenant. Null until it is issued.

ReferenceValue (object) or null

Response samples

Content type
application/json
{
  • "subscription_charge_id": "subc_1793404800",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "subscription_period": {
    },
  • "region_key": "ke",
  • "period_start": 0,
  • "period_end": 0,
  • "price": {
    },
  • "tax_display": "gross",
  • "amount_paid": {
    },
  • "paid_at": 0,
  • "provider_key": "stub",
  • "provider_subscription_id": "string",
  • "provider_invoice_id": "string",
  • "invoice": {
    }
}

Name the invoice issued for a charge (issuer callback)

The subscription-invoicing worker names the system tenant's invoice it issued for the charge. Set once: naming the same invoice again changes nothing, another one is a 409, and an invoice the system tenant did not issue is a 404. The name in the stored reference is the invoice's own. A charge with no invoice has not been invoiced yet.

Service-gated: not available to a tenant or to the agent.

Authorizations:
BearerAuth
path Parameters
subscription_charge_id
required
string
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label. Being readOnly, its required entry binds responses only (OpenAPI 3.1 §4.8.24.3).

In request bodies only _id is required. Both _class and _name are readOnly, so §4.8.24.3 binds their required entries to responses alone and a request body typed against this schema accepts the minimal {"_id": "bp_..."}. To clear a nullable reference, send null.

Responses

Response Schema: application/json
subscription_charge_id
required
string

Derived from period_start, so one billing period has one charge.

tenant_id
required
string
created_at
required
integer
updated_at
required
integer
required
object

The catalogue plan of the period, _id the plan key.

plan_name
required
string
required
object

The plan period the price was taken from.

region_key
required
string
period_start
required
integer

Unix seconds; inclusive.

period_end
required
integer

Unix seconds; exclusive.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

tax_display
required
string
Enum: "gross" "net"

Whether price includes VAT, from the catalogue row the period was priced from.

required
object (MonetaryAmount)

A monetary value with an ISO 4217 currency code.

currency may be null to denote the identity ("zero") element — {"amount": 0, "currency": null}. The identity absorbs into arithmetic (identity + x = x, x - x = identity, identity * n = identity); any non-zero amount must carry a currency. This is the wire form returned for an invoice draft whose totals haven't been computed yet.

Precision contract

amount is emitted as a JSON number carrying the server's Decimal with full precision — the server writes the Decimal's exact textual form as a raw JSON number token, bypassing any IEEE-754 round-trip. Sub-cent values such as 0.0003 USD (audiobook-streaming royalty rates, FX conversions, regulated reference prices) come over the wire exactly.

Client-side parsing

Standard JSON parsers convert JSON numbers to IEEE-754 floats, which lose precision for arithmetic on decimals that aren't power-of-10 fractions. Pick the right tool for the job:

  • Display only — the default float is fine. Both Python's repr(0.0003) and JavaScript's (0.0003).toString() return "0.0003", so user-visible numbers render correctly.
  • Exact arithmetic (summing line items, computing tax) — parse with a Decimal / BigDecimal type. Python: json.loads(text, parse_float=Decimal). JavaScript: a BigDecimal library such as big.js or decimal.js.

Client-side encoding for sub-cent values

A client that produces a sub-cent amount with json.dumps (Python) or JSON.stringify (JS) will also lose precision before the bytes leave the process — both encoders convert Decimal/BigDecimal to float first. Two paths preserve precision on the way in:

  1. Send the amount as a quoted decimal string. Request bodies schema this as MonetaryAmountInput, whose amount is a oneOf over number and string; the server's Pydantic coerces the string to an exact Decimal. (MonetaryAmount itself is the response shape and stays type: number.)
  2. Or use a JSON encoder on the client that supports raw number tokens (same trick as our server's encoder).

For everyday cent-precision values, sending a JSON number is fine.

paid_at
required
integer

Unix seconds.

provider_key
required
string
Enum: "stub" "stripe"
provider_subscription_id
required
string
provider_invoice_id
required
string or null

The provider's own invoice for the payment, such as a Stripe in_… id.

required
Reference (object) or null

Raccoon's own invoice for the charge, issued from the system tenant. Null until it is issued.

ReferenceValue (object) or null

Request samples

Content type
application/json
{
  • "invoice": {
    }
}

Response samples

Content type
application/json
{
  • "subscription_charge_id": "subc_1793404800",
  • "tenant_id": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "plan": {
    },
  • "plan_name": "string",
  • "subscription_period": {
    },
  • "region_key": "ke",
  • "period_start": 0,
  • "period_end": 0,
  • "price": {
    },
  • "tax_display": "gross",
  • "amount_paid": {
    },
  • "paid_at": 0,
  • "provider_key": "stub",
  • "provider_subscription_id": "string",
  • "provider_invoice_id": "string",
  • "invoice": {
    }
}

The subscription price list for one country

What a business in a given country pays Raccoon, in the currency they use. Served from the in-repo catalogue — no persistence, no third-party I/O.

Deliberately unauthenticated. The public marketing site puts a price on the homepage and must quote the same numbers the product charges; reading them from here is what stops the two drifting apart. Nothing tenant-specific is exposed — a price list is the most public document a company has.

Pass country to price a specific market, or region_key to price a pricing region directly — the form a signed-in tenant uses, since it carries a frozen region_key and no country. With neither, the response is priced for the us region.

Authenticating does not change the answer: a subscription's pricing region is fixed when it is created and is never re-derived here from an address that can later be edited. The caller says which market it wants priced; the endpoint does not guess from tenant data.

Prices are stored as explicit local amounts and are never computed from a live FX rate — a tenant's bill must not move because the shilling did.

query Parameters
region_key
string
Example: region_key=ke

Price for a pricing region directly, for a caller that already has one. A signed-in tenant carries a frozen region_key on its subscription and has no country to offer — and the key does not invert, since eu spans twenty of them. Takes precedence over country when both are given. An unknown key is a 422.

country
string = 2 characters

ISO 3166-1 alpha-2 code. A country with no price row of its own resolves to a USD region for its World Bank income group: us (high), world_b (upper middle), world_c (lower middle) or world_d (low). A territory the World Bank does not classify resolves to us. A code that is not an officially-assigned country is a 422.

Responses

Response Schema: application/json
required
Array of objects (BillingPlan)
next_token
required
null

The catalogue is a fixed short list and is never paginated.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": null
}

Changes

Poll the tenant change feed

Returns the changes recorded at or after since, oldest first, so a client can refresh whatever it has on screen that appears in the result. Each entry names a subject to re-read; none carries field values.

The response's next_token is a durable cursor, not a page marker: it is never null, and the client sends it back as since on the next poll. Omitting since subscribes from now and returns an empty page — a client that has just loaded has no backlog to catch up on.

Delivery is at-least-once. The cursor lags real time by a couple of seconds so a change written late within a second cannot be skipped, which means consecutive polls re-deliver a small overlap; de-duplicate on _id. Refetching is idempotent, so this is a deliberate trade.

Authorizations:
BearerAuth
query Parameters
since
string
Example: since=1785483570

Cursor from a previous response's next_token.

limit
integer [ 1 .. 200 ]
Default: 100

Responses

Response Schema: application/json
required
Array of objects (ChangeResponse)
next_token
required
string

The feed cursor, never null — unlike every other list endpoint, where next_token marks a page. Store it and send it back as since on the next poll. It deliberately lags real time by a couple of seconds, so consecutive polls re-deliver a small overlap; de-duplicate on _id.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "1785483570"
}

Read a single change row

Authorizations:
BearerAuth
path Parameters
change_id
required
string
Example: chg_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "change"
required
object (Reference)

The aggregate the client should re-read. _name is always empty — the feed never resolves it, both to keep a 200-row page to a single query and because a deleted subject no longer exists to name.

resource_class
required
string

Aggregate root class, e.g. product.

subclass
required
string

Fully-qualified path of what changed within the aggregate, e.g. product.price or business_partner.identifier.

method
required
string
Enum: "created" "updated" "deleted"
actor_kind
required
string

Who caused it — user, agent, service, or system.

created_at
required
integer

Unix epoch seconds. Also the feed's ordering position.

updated_at
required
integer

Unix epoch seconds.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
ReferenceValue (object) or null
object

Response samples

Content type
application/json
{
  • "_id": "chg_a1b2c3d4e5f6",
  • "_class": "change",
  • "subject": {
    },
  • "resource_class": "product",
  • "subclass": "product.price",
  • "method": "created",
  • "actor_kind": "agent",
  • "created_at": 0,
  • "updated_at": 0,
  • "_links": {
    },
  • "tenant": {
    },
  • "created_by": {
    }
}