Skip to navigation

Create an invoice

View as Markdown

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

AuthorizationBearer

JWT issued via POST /api/v1/auth/sign_in. Used by mobile and SPA clients. Revoked tokens are rejected.

OR
AuthorizationBearer

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

workspace_idlongRequired>=1
Workspace ID. The numeric ID shown in your URLs.

Headers

Idempotency-KeystringOptional<=255 characters

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

issuebooleanOptionalDefaults to false

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

This endpoint expects an object.
customer_idlong or stringRequired

Contact ID of the customer (from the contacts endpoints). Resolved to the contact’s legal entity, workspace-scoped. Required.

numberstringOptional
number_series_idlongOptional
issue_datedateOptional
delivery_datedateOptional
due_datedateOptional
due_daysintegerOptional

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.

expiry_datedateOptional
currencystringOptional
exchange_ratestringOptional

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).

payment_methodstringOptional
payment_typestringOptional
variable_symbolstringOptional
constant_symbolstringOptional
specific_symbolstringOptional
order_numberstringOptional
delivery_methodstringOptional

Delivery/carrier mode. Permitted by Params::DocumentParams for every document type.

show_payment_qrbooleanOptional

Per-document override for the payment QR code. Omit to inherit the workspace default.

payment_qr_formatenum or nullOptional

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.

Allowed values:
project_idlong or stringOptional

Project this document belongs to (from the projects API). Must be in this workspace.

round_totalbooleanOptional

Round the payable total to cash granularity (BT-114); the rounding delta is reported in totals.rounding.

quote_idlong or stringOptional
Quote this document was created from. Must be in this workspace.
sales_order_idlong or stringOptional

Sales order this invoice fulfils (from GET /sales_orders). Must be in this workspace.

bank_account_idlong or stringOptional

The bank account’s or cash register’s numeric id or its public_id (ba_…).

included_in_turnoverenumOptional
Allowed values:
reverse_chargebooleanOptional
reverse_charge_textstringOptional
discount_descriptionstringOptional
discount_percentagestringOptional
discount_amountstringOptional
opening_textstringOptional
closing_textstringOptional
footer_notestringOptional
recipient_notestringOptional
internal_notestringOptional
pdf_languageenumOptional

Language of the rendered PDF and customer e-mail. cz is a deprecated alias of cs: still accepted on input, never returned.

pdf_localestringOptional

Regional format for dates and amounts, a supported language-region tag such as “en-GB”.

mandatory_textstringOptional
hide_pricesbooleanOptional
proforma_idlong or stringOptional
Source proforma ID if converting from a proforma.
tax_document_idslist of longs or stringsOptional
delivery_note_idslist of longs or stringsOptional
line_itemslist of objectsOptional
auto_on_paymentbooleanOptional

Response

Created
idlong
public_idstringRead-onlyformat: "^[a-z]+_[0-7][0-9a-hjkmnp-tv-z]{25}$"

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, …).

typeenum

Document type discriminator. Always invoice on this endpoint — other types are exposed via their own endpoints (quotes, proformas, credit_notes).

Allowed values:
statusenum

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.

Allowed values:
currencystring

ISO-4217 currency code.

created_atdatetime
updated_atdatetime
payment_statusenum or nullOptional

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.

Allowed values:
overdueboolean or nullOptional
Whether a positive balance remains after the due date.
paid_lateboolean or nullOptional
Whether full settlement landed after the due date.
status_transitionsobjectOptional
numberstring or nullOptional

Invoice number (formatted via number_series, e.g. ‘FAK2026-0001’). Null for drafts.

issue_datedate or nullOptional
delivery_datedate or nullOptional
due_datedate or nullOptional
due_daysinteger or nullOptional
Default payment terms in days.
exchange_ratestring or nullOptionalformat: "decimal"
included_in_turnoverboolean or nullOptional
Whether this invoice counts toward the VAT registration threshold turnover calculation.
reverse_chargeboolean or nullOptional

Whether VAT reverse-charge applies (cross-border B2B).

reverse_charge_textstring or nullOptional
tax_schemestringOptional

Tax scheme (UNCL 5153), e.g. “VAT”.

order_numberstring or nullOptional
discount_descriptionstring or nullOptional
discount_percentagestring or nullOptionalformat: "decimal"
discount_amountstring or nullOptionalformat: "decimal"
opening_textstring or nullOptional
closing_textstring or nullOptional
footer_notestring or nullOptional
internal_notestring or nullOptional

Internal-only note. Not rendered on PDF or sent to recipient.

pdf_languagestring or nullOptional
pdf_localestring or nullOptional
delivery_methodstring or nullOptional

Delivery/carrier mode

email_sent_atdatetime or nullOptional
reminder_countinteger or nullOptional
Number of payment reminders sent to the client.
last_reminded_atdatetime or nullOptional
When the last payment reminder was sent.
amount_paidstring or nullOptionalformat: "decimal"

Amount settled so far (payments + advance deductions).

amount_duestring or nullOptionalformat: "decimal"

Outstanding amount (tax_inclusive − amount_paid).

paymentobjectOptional
import_sourceenum or nullOptional

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.

Allowed values:
totalsobjectOptional
settingsobjectOptional
line_itemslist of objectsOptional
customerobject or nullOptional

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.

supplierobject or nullOptional

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.

Errors

401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error