Invoices
List invoices
Returns a paginated list of invoices in a simplified preview shape. Use this endpoint for lists, sync flows, and quick overviews. For the full invoice payload, use the invoice detail endpoint.
GET
List invoices
Authorizations
Bearer token created for a specific company in Integrations → API.
Query Parameters
Filter by document number.
Filter by client.
Filter by payment status.
Available options:
paid, unpaid, partially_paid, overdue, will_not_be_paid Issue date from.
Issue date to.
Due date from.
Due date to.
Minimum total amount with VAT in company currency.
Maximum total amount with VAT in company currency.
Field used for sorting. Only values supported by the underlying invoice list filter are accepted.
Available options:
number, issueDate, dueDate, deliveryDate, totalWithVatEur Sorting direction.
Available options:
asc, desc Number of results per page.
Required range:
1 <= x <= 500Page number.
Required range:
x >= 1Previous
Create invoiceCreates 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:
1. explicit value from the payload,
2. client default values,
3. company document settings,
4. system resolver.
In practice, this means for example:
- `deliveryMethodId`, `paymentMethodId`, `currencyId`, and `languageId` may be resolved from the client or company settings,
- `number` and `numericalSeriesId` are resolved from the primary numbering series when omitted,
- `variableSymbol` is derived from the final document number when omitted,
- `bankAccountId` falls back to the primary company bank account when omitted,
- `currencyRate` is resolved from the currency and delivery date,
- if the final document currency is `EUR`, the backend always stores and returns `currencyRate = 1.0`, even when you send a different value,
- `issueDate` and `deliveryDate` default 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 `clientId` is omitted, the `client` object is used to match or create the client,
- when you send both `clientId` and `client`, `client` is applied only as a snapshot override for this document.
Matching is deterministic and follows this order:
- for companies: `vatId`, then `countryId + subjectId`, then `name + email`, then `name + street`,
- for people: `name + email`, then `name + 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:
1. as a manual item with its own name, unit, price, and VAT rate,
2. through `priceListItemId` and `quantity`,
3. through `priceListItemId` and 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:
```json
{
"clientId": 101,
"issueDate": "2026-03-04",
"items": [
{
"name": "Monthly retainer",
"quantity": 1,
"unitId": 1,
"unitPrice": 120.0,
"vatRate": 23
}
]
}
```
Inline client without `clientId`:
```json
{
"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:
```json
{
"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.
Next
List invoices