Create an invoice
Creates a new invoice. The type field is set by the route
(never sent in the request body) — this endpoint always
creates invoices.
Pass customer_id as the Contact ID returned by the contacts
endpoints; the API resolves it to that contact’s legal entity
(workspace-scoped). The workspace’s own Party is used as the
supplier automatically.
Authentication
JWT issued via POST /api/v1/auth/sign_in. Used by mobile and SPA clients. Revoked tokens are rejected.
Lucanto API key. Two prefixes:
lct_pat_<random><checksum>— personal access token (owner: User)lct_live_<random><checksum>— workspace token, live data
Issue keys at /settings/api_keys (personal) or
/:workspace_id/settings/api_keys (workspace). Plaintext token is
shown once and never again.
Path parameters
Headers
Client-supplied unique key (recommended: UUID v4) for safe
retries. Within 24 hours, repeating the same key with the same
request (method, path, query, body) replays the original
response instead of re-executing the action — once the action
has run, a 5xx included; a request stopped before it ran is not
stored. Reusing
a key with a different request returns
422 idempotency_key_conflict (IETF draft §2.7).
Query parameters
true creates the document and issues it in the same request: the
response is the issued document with its number drawn from the number
series, exactly as a create followed by POST …/{id}/issue. Atomic —
when issuing is refused (no number series, a lifecycle guard) nothing
is created and the response is a 422 with the reason, so nothing is
left to clean up (the issue ran and was refused, so an
Idempotency-Key replays that 422; retry with a new key). Issuing needs the manage: scope of the document type; a
write: key may create drafts only. Omitted, false or 0 creates a
draft; any value other than true/1/false/0, and issue sent
in the JSON body, is a 422.
Request
Contact ID of the customer (from the contacts endpoints). Resolved to the contact’s legal entity, workspace-scoped. Required.
Payment term in days. May be negative — the web form derives it as due_date − issue_date, and neither the model nor the controller constrains the sign.
Decimal rate as document-currency per 1 base-currency. Optional — when creating a foreign-currency document without it, the ECB reference rate for the issue date is filled automatically (supported currencies only; otherwise it stays unset, i.e. 1.0).
Delivery/carrier mode. Permitted by Params::DocumentParams for every document type.
Per-document override for the payment QR code. Omit to inherit the workspace default.
Per-document payment QR format. auto picks the format the customer’s banking app reads (PAY by square for Slovakia, QR Platba for Czechia, EPC QR for other EEA countries). Omit to inherit the workspace default; send null to go back to it.
Project this document belongs to (from the projects API). Must be in this workspace.
Round the payable total to cash granularity (BT-114); the rounding delta is reported in totals.rounding.
Sales order this invoice fulfils (from GET /sales_orders). Must be in this workspace.
The bank account’s or cash register’s numeric id or its public_id (ba_…).
Language of the rendered PDF and customer e-mail. cz is a deprecated alias of cs: still accepted on input, never returned.
Regional format for dates and amounts, a supported language-region tag such as “en-GB”.
Response
Stable public identifier of this record. Never changes once assigned.
Its prefix names the entity: doc_ document (invoice, proforma, credit
note, quote, sales order), exp_ expense, cnt_ contact, prj_
project, ba_ bank account or cash register, txn_ transaction,
lon_ loan, bst_ bank statement. Accepted in place of the numeric
id in this resource’s path parameters and in request fields that
reference it (customer_id, bank_account_id, …).
Document type discriminator. Always invoice on this
endpoint — other types are exposed via their own endpoints
(quotes, proformas, credit_notes).
Invoice lifecycle state: draft, issued, sent,
reopened, or canceled. reopened is where
reopenInvoice lands a
previously locked invoice; it is editable again and must be
re-issued. Settlement is reported separately by
payment_status; POST /:id/mark_paid does not change this
lifecycle field.
ISO-4217 currency code.
Derived settlement degree (money is the source of truth). Null for non-payable document types, drafts, canceled documents, and rows created before the payment_status backfill ran.
Invoice number (formatted via number_series, e.g. ‘FAK2026-0001’). Null for drafts.
Whether VAT reverse-charge applies (cross-border B2B).
Tax scheme (UNCL 5153), e.g. “VAT”.
Internal-only note. Not rendered on PDF or sent to recipient.
Delivery/carrier mode
Amount settled so far (payments + advance deductions).
Outstanding amount (tax_inclusive − amount_paid).
Origin of the document. null when it was created in Lucanto, in which case totals are Lucanto’s EN 16931 calculation. A non-null value means the document was imported from that system and initially carries the source system’s own figures, preserved verbatim; those may differ by cents from Lucanto’s calculation because systems round VAT at different levels (line vs. category). insight means AI extraction from an uploaded file, not an import from another vendor. This records provenance only, not which calculation is currently in effect — editing line items or document discounts recomputes totals in Lucanto while leaving import_source set. In practice a document only ever carries kros_developer, isdoc, superfaktura or null. kros appears only on rows imported before the writer was renamed, and insight is written by the expense path only. The enum is kept as the union across resources rather than narrowed, so a legacy row cannot fail validation.
The party identity as it appears on a document. On an ISSUED document this is the identity the document was issued with — a snapshot pinned at issue, which does NOT change when the legal entity is later renamed, re-registered, or moved. A draft follows the entity’s current identity. id is the legal entity’s id and is stable across identity changes, so a stored reference keeps resolving. This matches the PDF and the ISDOC export of the same document. vat_period is not part of this projection — a counterparty’s filing period is not knowable.
The party identity as it appears on a document. On an ISSUED document this is the identity the document was issued with — a snapshot pinned at issue, which does NOT change when the legal entity is later renamed, re-registered, or moved. A draft follows the entity’s current identity. id is the legal entity’s id and is stable across identity changes, so a stored reference keeps resolving. This matches the PDF and the ISDOC export of the same document. vat_period is not part of this projection — a counterparty’s filing period is not knowable.
