Get, update, or delete an invoice
API Documentation / Resources / Invoices
Get an invoice
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices/{invoice_id}
Required OAuth scope: invoices:read
Returns one normalized document including calculated totals and lines.
| Context rule | Behavior |
|---|---|
| Document belongs to the granted subsidiary | The representation is returned. |
| Document is absent or outside the grant | 404 Not Found; existence is not disclosed. |
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. |
invoice_id |
path | Yes | string (uuid) | UUID of the invoice, bill, or credit note. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices/{invoice_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Invoice details. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Invoice does not exist in the granted accounting context. |
200 example
HTTP/1.1 200 OK
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"
}
}
Update an invoice
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices/{invoice_id}
Required OAuth scope: invoices:write
Updates supplied fields; omitted fields remain unchanged. Supplying
lines replaces the complete line collection.
| State | Mutable data |
|---|---|
DRAFT |
Document fields and lines. |
AUTHORISED |
Financial values are immutable. |
| Allocated or paid | Remove settlements or allocations before financial correction. |
VOIDED |
Cannot be reopened. |
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. |
invoice_id |
path | Yes | string (uuid) | UUID of the invoice, bill, or credit note. |
Request
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices/{invoice_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"due_date": "2026-09-20",
"reference": "PO-1042-REV1"
}
Required body fields: None.
Responses
| Status | Description |
|---|---|
200 |
Updated invoice. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Invoice does not exist in the granted accounting context. |
409 |
Request conflicts with the invoice lifecycle or accounting state. |
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": 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"
}
}
Delete an invoice draft
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices/{invoice_id}
Required OAuth scope: invoices:write
Deletes a draft document without creating ledger activity.
| State | Result |
|---|---|
| Unposted draft without allocations | 204 No Content. |
| Authorised or paid document | 409 invoice_not_draft. |
| Document with credit allocations | 409 invoice_has_allocations. |
Posted documents use the void or credit-note lifecycle to preserve their accounting audit trail.
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. |
invoice_id |
path | Yes | string (uuid) | UUID of the invoice, bill, or credit note. |
Request
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices/{invoice_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
204 |
Draft deleted. The response has no body. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Invoice does not exist in the granted accounting context. |
409 |
Request conflicts with the invoice lifecycle or accounting state. |