> ## Documentation Index
> Fetch the complete documentation index at: https://developers.novala.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Invoices API — List, Retrieve, and Update Invoices
> Access invoice records with line items and payment history. Filter by status and date range, and update notes, due dates, and custom fields via PATCH.
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
Filter by invoice status. One of: `draft`, `sent`, `viewed`, `partially_paid`, `paid`, `overdue`, `voided`.
Search by invoice number or company name (case-insensitive).
Return invoices with `issuedDate` on or after this date (`YYYY-MM-DD`).
Return invoices with `issuedDate` on or before this date (`YYYY-MM-DD`).
1-based page index.
Results per page. Maximum `100`.
### Response
```json theme={null}
{
"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
}
```
```bash cURL theme={null}
curl -X GET "https://app.novala.ai/api/invoices?status=sent&dateFrom=2024-07-01" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```typescript TypeScript theme={null}
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
UUID of the invoice.
### Response fields
UUID of the invoice.
Human-readable invoice number (for example, `INV-2024-0042`).
Current status of the invoice.
UUID of the billed company.
UUID of the associated contact.
UUID of the originating quote, if any.
Issue date (`YYYY-MM-DD`).
Payment due date (`YYYY-MM-DD`).
Subtotal before tax as a decimal string.
Tax rate as a decimal string (for example, `"0.08"` for 8%).
Calculated tax amount.
Total amount including tax.
Total amount paid to date.
Remaining balance.
Internal notes.
Notes visible to the customer on the invoice.
Custom field key-value pairs.
Timestamp when the invoice was sent.
Timestamp when the invoice was fully paid.
Company name.
Billing address.
First name.
Last name.
Email address.
UUID.
Line item description.
Quantity as a decimal string.
Unit price as a decimal string.
Line total (`quantity × unitPrice`).
Display order.
UUID.
Amount paid.
Date of payment (`YYYY-MM-DD`).
One of `check`, `ach`, `credit_card`, `cash`, `other`.
Check number or transaction ID.
Payment notes.
```bash cURL theme={null}
curl -X GET https://app.novala.ai/api/invoices/inv-uuid-001 \
-H "Authorization: Bearer YOUR_API_KEY"
```
```typescript TypeScript theme={null}
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
UUID of the invoice to update.
### Request body
All fields are optional.
Updated internal notes. Pass `null` to clear.
Updated customer-facing notes. Pass `null` to clear.
Updated due date (`YYYY-MM-DD`). Pass `null` to clear.
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.
```bash cURL theme={null}
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."
}'
```
```typescript TypeScript theme={null}
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();
```