finov.ioDocumentationHome

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.