Invoices API — List, Retrieve, and Update Invoices

Invoices track billable amounts sent to companies. Each invoice moves through a lifecycle from draft to payment and includes line items, tax calculations, and payment records. You can filter the list by status and date, retrieve full detail with line items and payments, and update metadata fields via PATCH.

All invoice endpoints are scoped to your tenant. Pass your API key in the Authorization: Bearer header on every request.

Invoice statuses

Status	Meaning
`draft`	Created but not yet sent.
`sent`	Sent to the customer.
`viewed`	Customer has opened the invoice.
`partially_paid`	Payment received but balance remains.
`paid`	Fully paid.
`overdue`	Past the due date and unpaid.
`voided`	Cancelled; no payment expected.

List invoices

GET /api/invoices Returns a paginated list of invoices for the authenticated tenant, with company name included in each row.

Query parameters

string

Filter by invoice status. One of: draft, sent, viewed, partially_paid, paid, overdue, voided.

string

Search by invoice number or company name (case-insensitive).

string

Return invoices with issuedDate on or after this date (YYYY-MM-DD).

string

Return invoices with issuedDate on or before this date (YYYY-MM-DD).

integer

default:"1"

1-based page index.

integer

default:"25"

Results per page. Maximum 100.

Response

{
  "data": [
    {
      "id": "inv-uuid-001",
      "invoiceNumber": "INV-2024-0042",
      "status": "sent",
      "companyName": "Acme Corp",
      "issuedDate": "2024-07-01",
      "dueDate": "2024-07-31",
      "totalAmount": "4500.00",
      "amountPaid": "0.00",
      "balanceDue": "4500.00",
      "createdAt": "2024-07-01T10:00:00Z"
    }
  ],
  "total": 15
}

curl -X GET "https://app.novala.ai/api/invoices?status=sent&dateFrom=2024-07-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({ status: 'sent', dateFrom: '2024-07-01' });
const response = await fetch(`https://app.novala.ai/api/invoices?${params}`, {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});
const { data, total } = await response.json();

Get an invoice

GET /api/invoices/{id} Retrieves a full invoice record with company details, optional contact, all line items, and all payment records.

Path parameters

string

required

UUID of the invoice.

Response fields

string

UUID of the invoice.

string

Human-readable invoice number (for example, INV-2024-0042).

string

Current status of the invoice.

string

UUID of the billed company.

string | null

UUID of the associated contact.

string | null

UUID of the originating quote, if any.

string | null

Issue date (YYYY-MM-DD).

string | null

Payment due date (YYYY-MM-DD).

string

Subtotal before tax as a decimal string.

string

Tax rate as a decimal string (for example, "0.08" for 8%).

string

Calculated tax amount.

string

Total amount including tax.

string

Total amount paid to date.

string

Remaining balance.

string | null

Internal notes.

string | null

Notes visible to the customer on the invoice.

object

Custom field key-value pairs.

string | null

Timestamp when the invoice was sent.

string | null

Timestamp when the invoice was fully paid.

object

Show Company object

string

Company name.

string | null

Billing address.

object | null

Show Contact object

string

First name.

string

Last name.

string | null

Email address.

array

Show Line item object

string

UUID.

string

Line item description.

string

Quantity as a decimal string.

string

Unit price as a decimal string.

string

Line total (quantity × unitPrice).

integer

Display order.

array

Show Payment object

string

UUID.

string

Amount paid.

string

Date of payment (YYYY-MM-DD).

string

One of check, ach, credit_card, cash, other.

string | null

Check number or transaction ID.

string | null

Payment notes.

curl -X GET https://app.novala.ai/api/invoices/inv-uuid-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://app.novala.ai/api/invoices/inv-uuid-001', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});
const invoice = await response.json();
// invoice.lineItems, invoice.payments, invoice.balanceDue, etc.

Update an invoice

PATCH /api/invoices/{id} Updates metadata fields on an invoice. Status transitions (sending, voiding, recording payments) are handled by sub-routes not covered here; this endpoint is for notes, due date, and custom field overrides.

Path parameters

string

required

UUID of the invoice to update.

Request body

All fields are optional.

string | null

Updated internal notes. Pass null to clear.

string | null

Updated customer-facing notes. Pass null to clear.

string | null

Updated due date (YYYY-MM-DD). Pass null to clear.

object

Replaces all custom field values with the provided map.

Response

Returns 200 OK with the updated invoice object. Returns 404 Not Found if the invoice does not exist or belongs to a different tenant.

curl -X PATCH https://app.novala.ai/api/invoices/inv-uuid-001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDate": "2024-08-15",
    "customerNotes": "Please remit via ACH to the account on file."
  }'

const response = await fetch('https://app.novala.ai/api/invoices/inv-uuid-001', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dueDate: '2024-08-15',
    customerNotes: 'Please remit via ACH to the account on file.',
  }),
});
const updated = await response.json();

Overview

Endpoints

Invoices API — List, Retrieve, and Update Invoices

Invoice statuses

List invoices

Query parameters

Response

Get an invoice

Path parameters

Response fields

Update an invoice

Path parameters

Request body

Response

​Invoice statuses

​List invoices

​Query parameters

​Response

​Get an invoice

​Path parameters

​Response fields

​Update an invoice

​Path parameters

​Request body

​Response

Invoice statuses

List invoices

Query parameters

Response

Get an invoice

Path parameters

Response fields

Update an invoice

Path parameters

Request body

Response