List invoices or create a draft
API Documentation / Resources / Invoices
List invoices
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices
Required OAuth scope: invoices:read
Lists invoices, bills, and credit notes visible in the subsidiary.
| Filter | Meaning |
|---|---|
type |
Exact normalized document type. |
status |
Exact normalized lifecycle status. |
contact_id |
Documents for one customer or supplier. |
invoice_number |
Exact assigned document number. |
from_date, to_date |
Inclusive document-date range. |
due_from, due_to |
Inclusive due-date range. |
updated_since |
Changed at or after an RFC 3339 timestamp. |
search |
Number, reference, or contact-name search. |
Sort by date, due_date, invoice_number, created_at, or
updated_at. The default is date DESC, then stable resource order.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary containing the documents. |
type |
query | No | string: SALES_INVOICE, SALES_CREDIT_NOTE, PURCHASE_INVOICE, PURCHASE_CREDIT_NOTE | |
status |
query | No | string: DRAFT, AUTHORISED, PAID, VOIDED | |
contact_id |
query | No | string (uuid) | |
invoice_number |
query | No | string | |
from_date |
query | No | string (date) | |
to_date |
query | No | string (date) | |
due_from |
query | No | string (date) | |
due_to |
query | No | string (date) | |
updated_since |
query | No | string (date-time) | |
search |
query | No | string | |
page |
query | No | integer | Positive page number. |
per_page |
query | No | integer | Records per page. |
sort |
query | No | string: date, due_date, invoice_number, created_at, updated_at | |
order |
query | No | string: asc, desc |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of normalized invoices. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
422 |
Invoice data or referenced accounting configuration failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "f54ca5ce-c915-417b-9514-818ba58a21cb",
"invoice_number": "INV-2026-0042",
"type": "SALES_INVOICE",
"status": "AUTHORISED",
"contact_id": "a68d68ec-5866-42e5-8864-57829d3f91b5",
"date": "2026-08-10",
"due_date": "2026-09-09",
"reference": "PO-1042",
"currency_code": "NZD",
"exchange_rate": null,
"branding_theme_id": null,
"subtotal": "1500.0000",
"tax_total": "225.0000",
"total": "1725.0000",
"amount_due": "1725.0000",
"lines": [
{
"id": "13185dbb-f413-4836-85ed-6435f0286d86",
"description": "Advisory services",
"quantity": "2.0000",
"unit_amount": "750.0000",
"discount_rate": "0.0000",
"account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c31",
"tax_rate_id": "d98226c2-ad80-4345-b117-5630de766842",
"dimension_element_ids": [],
"subtotal": "1500.0000",
"tax_amount": "225.0000",
"total": "1725.0000"
}
],
"journal_id": "553aa91a-e8c2-4c6f-b800-07a2b92efdb1",
"reversal_journal_id": null,
"authorised_at": "2026-08-10T13:30:00Z",
"voided_at": null,
"created_at": "2026-08-10T13:15:00Z",
"updated_at": "2026-08-10T13:30:00Z"
}
],
"meta": {
"current_page": 1,
"per_page": 30,
"last_page": 1,
"total": 1
}
}
Create an invoice draft
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices
Required OAuth scope: invoices:write
Creates a draft invoice, bill, or credit note. Finovio calculates every line subtotal, tax amount, and document total.
| Input | Contract |
|---|---|
| Monetary and quantity values | Decimal strings, never JSON numbers. |
| Contact, account, tax, and dimensions | Active UUIDs visible to the subsidiary. |
| Currency | Enabled ISO 4217 code with valid exchange-rate context. |
| Lines | At least one line; line order is preserved. |
Creation does not post to the ledger. Use the authorise operation after reviewing the calculated representation.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary containing the documents. |
Request
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"type": "SALES_INVOICE",
"contact_id": "a68d68ec-5866-42e5-8864-57829d3f91b5",
"date": "2026-08-10",
"due_date": "2026-09-09",
"reference": "PO-1042",
"currency_code": "NZD",
"lines": [
{
"description": "Advisory services",
"quantity": "2.0000",
"unit_amount": "750.0000",
"discount_rate": "0.0000",
"account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c31",
"tax_rate_id": "d98226c2-ad80-4345-b117-5630de766842",
"dimension_element_ids": []
}
]
}
Required body fields: type, contact_id, date, due_date, currency_code, lines.
Responses
| Status | Description |
|---|---|
201 |
Invoice draft created. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
409 |
Request conflicts with the invoice lifecycle or accounting state. |
422 |
Invoice data or referenced accounting configuration failed validation. |
201 example
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "f54ca5ce-c915-417b-9514-818ba58a21cb",
"invoice_number": null,
"type": "SALES_INVOICE",
"status": "DRAFT",
"contact_id": "a68d68ec-5866-42e5-8864-57829d3f91b5",
"date": "2026-08-10",
"due_date": "2026-09-20",
"reference": "PO-1042-REV1",
"currency_code": "NZD",
"exchange_rate": null,
"branding_theme_id": null,
"subtotal": "1500.0000",
"tax_total": "225.0000",
"total": "1725.0000",
"amount_due": "1725.0000",
"lines": [
{
"id": "13185dbb-f413-4836-85ed-6435f0286d86",
"description": "Advisory services",
"quantity": "2.0000",
"unit_amount": "750.0000",
"discount_rate": "0.0000",
"account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c31",
"tax_rate_id": "d98226c2-ad80-4345-b117-5630de766842",
"dimension_element_ids": [],
"subtotal": "1500.0000",
"tax_amount": "225.0000",
"total": "1725.0000"
}
],
"journal_id": null,
"reversal_journal_id": null,
"authorised_at": null,
"voided_at": null,
"created_at": "2026-08-10T13:15:00Z",
"updated_at": "2026-08-10T13:25:00Z"
}
}