Unapprove Invoice
Revokes the invoice’s approval — the invoice.unapproved action: it clears
approved / approvedAt and posts NOTHING to the books. The inverse of
approve.
Authority. Granting and revoking an approval are the SAME authority:
the calling key must hold company.payment:approve. The company’s in-app
approval rules are never applied to API callers. A key without the
permission gets 403.
Preconditions (422). The invoice must not be paid or partially paid
(UNAPPROVE_PAID) — once money has moved, the approval that authorized it
cannot be revoked, so
remove the payments first. It
must also be neither voided (INVOICE_VOIDED) nor deleted
(INVOICE_DELETED). Unapproving a never-approved invoice is a DEFINED
no-op: still journaled, zero ledger rows, refreshed state returned.
Concurrency + idempotency. Requires If-Match (the invoice’s current
headJournalId); the body carries the client-minted actionId — an
identical retry replays the original outcome.
Required permission: company.payment:approve
Authorizations
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
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
Company identifier
Invoice identifier
Body
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
Optional display label for the source system's author. Stamped as the journal record's display attribution; the acting principal stays the External API service user. Ignored on idempotent replays
1 - 255Response
The invoice with its approval revoked — refreshed read state (approved: false)
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.
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)
1THE invoice representation — the same shape everywhere an endpoint returns an invoice (listing rows, the detail read, and every write's refreshed-row response). headJournalId is the invoice's current journal head — the optimistic-concurrency token subsequent writes echo back as If-Match.
The invoice's live payment marks after the write, newest first
