finov.ioDocumentationHome

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"
  }
}