Create Invoice
Creates one invoice — the invoice.created action. The server mints the
invoice id and its display number (INV-XXXXXX-XXX) and returns the
whole refreshed document: the invoice row (with headJournalId, the
If-Match watermark for every subsequent write) and its (empty) payment
list. No If-Match on create.
Idempotency. actionId is a client-minted uuid that becomes the
action’s journal id. Retrying the identical request replays the original
outcome — server-minted invoice id and number included — instead of
creating twice; reusing the id with a different payload is
409 ACTION_ID_REUSED.
Links. links is optional: an invoice may link to an event, plus an
optional payee. A request with links.policy is well-formed but refused
with 422 POLICY_INVOICE_BATCH_ONLY: policy invoice documents are created,
voided, and replaced only through the atomic
policy invoice batch.
Parsed invoices typically arrive unlinked and attach later via
re-link for the price of one
action. Named targets must exist (422 LINK_TARGET_MISSING).
Configuration ids. categoryId and every line item’s
lineItemTypeId must come from the company’s configured vocabulary —
discover them with
GET /api/v1/companies/{companyId}/financials/config/categories. A type
outside the cited category is 422 UNKNOWN_ID; a deprecated category is
422 DEPRECATED_CONFIG.
Recognition dates. incurredDate is a recognition date — which period
the amount lands in. On an event-linked or unlinked invoice a future
incurredDate is 422 FUTURE_DATE. Scheduled policy installments use the
policy invoice batch instead. Payment dates are never allowed in the future.
Drafts. Pass stage: "draft" to create the invoice UNPOSTED — it gets
the derived status draft and posts nothing to the ledger until
finalize. This is the only
place a draft is born; draft-ness thereafter lives in the journal. A draft
parsed off an already-paid document may carry its payment marks as the
draftPayments annex (per-line settlement marks citing this payload’s own
line items — no paymentId, server-assigned at finalize) — legal only
with the draft stage, and materialized as real payment marks when the
draft is finalized.
Source documents. sourceFileIds attaches already-uploaded files to
the created invoice server-side (one placement per file). Upload the bytes
first through the platform files API, then pass their ids here; an unknown
id is a 404 that rolls the whole create back. Attaching does not require
the draft stage.
Required permission: company.payment:update
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.
Path Parameters
Company 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
The transaction category the invoice belongs to
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
1 - 255Set to draft to create the invoice UNPOSTED (derived status draft) until it is finalized. Omit for a live, posted invoice. The only stage marker — accepted on create only
draft The recognition date for the charges (ISO YYYY-MM-DD) — the period the amount lands in. May be in the future on a policy-linked invoice; on an event-linked or unlinked invoice a future date is 422 FUTURE_DATE
When payment is owed — display metadata only
Free-text memo
Values for the tenant-defined custom invoice fields, keyed by field referenceId — an opaque JSON object
The invoice's initial links — all optional; absent means unlinked. event and policy are mutually exclusive
Payment MARKS parsed off an already-paid source document, carried on a DRAFT so finalize can apply them as real payments. Legal only with stage: "draft". One entry = one per-line settlement mark citing this payload's own line items; no paymentId — the server assigns ids at finalize
Ids of already-uploaded files (platform files API) to attach to the created invoice server-side. Deduplicated; an unknown id is a 404 that rolls the create back
Response
The created invoice — refreshed read state with the server-minted id and invoice number (a replay returns the original outcome)
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