Create invoice
Creates a new invoice.
Recommended flow
The recommended happy path is to send clientId and items. This is the simplest flow when the client already exists in Fintoro.
If the client does not exist yet or you do not want to perform a separate client create step, send the client object without clientId. The backend attempts to match an existing client and creates a new one only when no match is found.
If you send both clientId and client, the client object acts as a sparse snapshot override for this specific document. This lets you adjust, for example, the delivery address or contact details only for this invoice without changing the stored client record.
How defaults are resolved
Most document fields are optional. The backend resolves them in this order:
- explicit value from the payload,
- client default values,
- company document settings,
- system resolver.
In practice, this means for example:
deliveryMethodId,paymentMethodId,currencyId, andlanguageIdmay be resolved from the client or company settings,numberandnumericalSeriesIdare resolved from the primary numbering series when omitted,variableSymbolis derived from the final document number when omitted,bankAccountIdfalls back to the primary company bank account when omitted,currencyRateis resolved from the currency and delivery date,- if the final document currency is
EUR, the backend always stores and returnscurrencyRate = 1.0, even when you send a different value, issueDateanddeliveryDatedefault to today.
How client resolution works
Client resolution is strictly deterministic:
- when you send
clientId, the backend loads that client by ID within the token scope, - when
clientIdis omitted, theclientobject is used to match or create the client, - when you send both
clientIdandclient,clientis applied only as a snapshot override for this document.
Matching is deterministic and follows this order:
- for companies:
vatId, thencountryId + subjectId, thenname + email, thenname + street, - for people:
name + email, thenname + street.
If no match is found, a new client is created. If more than one client matches, the backend uses the first record in a stable order.
If you send an explicit clientId that does not exist or is outside the token scope, the endpoint returns a 422 validation error on clientId.
If you send an explicit bankAccountId and that record does not exist or is outside the token scope, the endpoint returns a 422 validation error on bankAccountId.
If you omit bankAccountId and the company has no primary bank account configured, the endpoint returns 422.
How line items work
A line item can be created in three ways:
- as a manual item with its own name, unit, price, and VAT rate,
- through
priceListItemIdandquantity, - through
priceListItemIdand sparse overrides for selected fields such as the price or name.
If you send a discount without discountName, the backend fills in a localized default discount label based on the document language.
Request examples
Existing client with a manual item:
{
"clientId": 101,
"issueDate": "2026-03-04",
"items": [
{
"name": "Monthly retainer",
"quantity": 1,
"unitId": 1,
"unitPrice": 120.0,
"vatRate": 23
}
]
}
Inline client without clientId:
{
"client": {
"type": "company",
"name": "Acme s.r.o.",
"email": "billing@acme.test",
"countryId": 703,
"subjectId": "12345678",
"street": "Hlavna 1",
"city": "Bratislava",
"zip": "81101"
},
"items": [
{
"name": "API implementation",
"quantity": 10,
"unitId": 7,
"unitPrice": 80.0,
"vatRate": 23
}
]
}
Price list item with the minimum payload:
{
"clientId": 101,
"items": [
{
"priceListItemId": 501,
"quantity": 2
}
]
}
If you send an Idempotency-Key, the same key with the same payload returns the original response without creating the invoice again.
Authorizations
Bearer token created for a specific company in Integrations → API.
Headers
Optional request identifier for safe retries. Use a unique value for each create request you want to retry safely.
"invoice-create-2026-03-03-001"
Body
- Option 1
- Option 2
Payload used to create an invoice. The usual happy path is clientId plus items; the backend can resolve many other values automatically. You must send either clientId or client.
Existing client ID. This is the recommended way to create an invoice. If you also send the client object, it is applied as a sparse snapshot override for this specific document.
101
Invoice line items. This field stays required even when the backend resolves most other values automatically.
1 - 100 elementsPayload for a single invoice line item. Three modes are supported: a manual item, priceListItemId + quantity, or priceListItemId with sparse override fields. quantity is always required. If you omit priceListItemId, you must also send name, unitPrice, and vatRate. unitId is optional; when you omit it for a manual item, the backend defaults to unit 1 (piece / Unit::Piece). If you send priceListItemId, the backend can hydrate the name, unit, unit price, and VAT rate from the price list item, and the payload acts only as a sparse override.
- Option 1
- Option 2
Manual invoice number. If omitted, the backend generates it from the numbering series. If you send number, do not send numericalSeriesId in the same payload.
1 - 20"20260001"
Optional ID of the proforma invoice the invoice is created from.
401
Optional ID of the order the invoice is created from.
501
Optional ID of the quotation the invoice is created from.
601
Sparse client payload. When clientId is sent, it overrides the client snapshot for this document only. When clientId is omitted, the backend uses it to match or create the client.
Optional business case ID. When sent, it must be available in the token scope and to the client resolved as the final clientId.
701
Numbering series ID. If omitted together with number, the primary invoice series is used. If you send numericalSeriesId, do not send manual number in the same payload.
12
Bank account ID to use on the invoice. It must be available in the token scope. If omitted, the primary company bank account is used. If the company has no primary bank account configured, the endpoint returns a 422 validation error on bankAccountId.
201
Issue date in Y-m-d format. It must be after 2009-01-01 and before a date one year in the future. If omitted, today's date is used.
"2026-03-03"
Number of due days. Precedence is payload → client default → company document settings.
0 <= x <= 100014
Delivery date in Y-m-d format. If sent, it must be less than or equal to issueDate. If omitted, issueDate is used.
"2026-03-03"
Variable symbol. Allowed values have 1 to 10 digits. If omitted, the backend derives it from the final invoice number.
0 <= x <= 999999999920260001
Constant symbol. Allowed values have 1 to 4 digits. Precedence is payload → client default → null.
0 <= x <= 9999308
Specific symbol. Allowed values have 1 to 10 digits. Precedence is payload → client default → null.
0 <= x <= 999999999955
Document-level discount type.
percentage, fixed "percentage"
Document-level discount value.
x >= 010
Reverse-charge tax liability flag. If omitted, false is used.
false
Delivery method ID from the delivery method reference table. Precedence is payload → client default → company document settings.
1
Payment method ID from the payment method reference table. Precedence is payload → client default → company document settings.
1
Currency ID from the currency reference table. Precedence is payload → client default → company document settings.
1
Currency exchange rate against EUR. If omitted, the backend resolves it server-side from currencyId and deliveryDate. If the final document currency is EUR, the backend always stores and returns 1.0.
0.00001 <= x <= 100000001
Language ID from the language reference table. Precedence is payload → client default → company document settings.
1
QR type ID from the QR type reference table. If omitted, the company document settings value is used.
1
Note shown on the document. Precedence is payload → client default → company document settings.
3000"Thank you for your order."
Text shown above the line items. Precedence is payload → client default → company document settings.
3000"Thank you for working with us."
Response
Invoice created.
Invoice.
301
"6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19"
"invoice"
"20260001"
Absolute URL of the public web document for this invoice.
"https://app.fintoro.sk/web-doklad/fa/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1"
Absolute URL of the Fintoro API endpoint that downloads this invoice PDF as an attachment.
"https://app.fintoro.sk/api/public/v1/invoices/123/pdf"
Supplier snapshot stored directly on this document.
Live ID of the client linked to the invoice.
101
Historical client snapshot stored directly on this document.
Bank account linked to the invoice as a live relation loaded through soft delete.
Payments linked to this invoice ordered from newest to oldest.
20260001
308
55
"2026-03-03"
"2026-03-17"
"2026-03-03"
Optional business case ID. When sent, it must belong to the client selected on the document.
701
"percentage"
10
false
12
Delivery method ID from the delivery method reference table.
1
Payment method ID from the payment method reference table.
1
Currency ID from the currency reference table.
1
1
Language ID from the language reference table.
1
QR type ID from the QR type reference table.
1
"Thank you for your order."
"Thank you for working with us."
200
240
200
240
240
"unpaid"
true
0