Skip to main content
POST

Authorizations

Authorization
string
header
required

API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey, and do not use an X-API-Key header; those are not accepted.

Headers

If-Match
string<uuid>
required

The invoice's current headJournalId — the optimistic-concurrency watermark every single-invoice write after creation must send. Read it off any invoice read or write response and echo it verbatim (a bare uuid; an entity-tag dressing of it — "uuid" or W/"uuid" — is also accepted). Missing or malformed is a 400 (IF_MATCH_REQUIRED / IF_MATCH_INVALID); a stale value is a 409 IF_MATCH_CONFLICT whose body carries the current invoice. An idempotent actionId replay short-circuits BEFORE the watermark is evaluated.

Path Parameters

companyId
string<uuid>
required

Company identifier

invoiceId
string<uuid>
required

Invoice identifier

Body

application/json
actionId
string<uuid>
required

Client-minted idempotency key — becomes the action's journal id. An identical retry replays the original outcome; reuse with a different payload is 409 ACTION_ID_REUSED

to
string<uuid> | null
required

The new payee entity's id, or null to clear

author
string

Optional display label for the source system's author (e.g. the integrator-side user). Stamped as the journal record's display attribution; the acting principal stays the External API service user, so a label can never impersonate an in-app user. Ignored on idempotent replays

Required string length: 1 - 255

Response

The invoice with its new payee — refreshed read state

The response of every single-invoice write — refreshed read state, not an ack: the emitted journal id(s), THE invoice row (identical shape to the reads — one invoice representation everywhere; its headJournalId is the next If-Match), and the invoice's live payments. An idempotent actionId replay returns this same shape rebuilt from the original outcome, server-minted values included.

journalIds
string<uuid>[]
required

Every journal id the write emitted — the anchor action's id (the actionId you supplied) first, then any engine-minted siblings (a multi-mark payment's additional marks) and any companion the horizon rule composed (e.g. the reserve unwind of a pre-horizon eroding payment's removal, or a delete's payment sweep)

Minimum array length: 1
invoice
object
required

THE invoice representation — the same shape everywhere an endpoint returns an invoice (listing rows, the detail read, and every write's refreshed-row response; the policy invoice batch's rows also carry approvedBy). headJournalId is the invoice's current journal head — the optimistic-concurrency token subsequent writes echo back as If-Match.

payments
object[]
required

The invoice's live payment marks after the write, newest first