Skip to main content

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

StatusMeaning
draftCreated but not yet sent.
sentSent to the customer.
viewedCustomer has opened the invoice.
partially_paidPayment received but balance remains.
paidFully paid.
overduePast the due date and unpaid.
voidedCancelled; 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

​
status
string
Filter by invoice status. One of: draft, sent, viewed, partially_paid, paid, overdue, voided.
​
search
string
Search by invoice number or company name (case-insensitive).
​
dateFrom
string
Return invoices with issuedDate on or after this date (YYYY-MM-DD).
​
dateTo
string
Return invoices with issuedDate on or before this date (YYYY-MM-DD).
​
page
integer
default:"1"
1-based page index.
​
limit
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"

​
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

​
id
string
required
UUID of the invoice.

​
Response fields

​
id
string
UUID of the invoice.
​
invoiceNumber
string
Human-readable invoice number (for example, INV-2024-0042).
​
status
string
Current status of the invoice.
​
companyId
string
UUID of the billed company.
​
contactId
string | null
UUID of the associated contact.
​
quoteId
string | null
UUID of the originating quote, if any.
​
issuedDate
string | null
Issue date (YYYY-MM-DD).
​
dueDate
string | null
Payment due date (YYYY-MM-DD).
​
subtotal
string
Subtotal before tax as a decimal string.
​
taxRate
string
Tax rate as a decimal string (for example, "0.08" for 8%).
​
taxAmount
string
Calculated tax amount.
​
totalAmount
string
Total amount including tax.
​
amountPaid
string
Total amount paid to date.
​
balanceDue
string
Remaining balance.
​
notes
string | null
Internal notes.
​
customerNotes
string | null
Notes visible to the customer on the invoice.
​
customFields
object
Custom field key-value pairs.
​
sentAt
string | null
Timestamp when the invoice was sent.
​
paidAt
string | null
Timestamp when the invoice was fully paid.
​
company
object
​
contact
object | null
​
lineItems
array
​
payments
array
curl -X GET https://app.novala.ai/api/invoices/inv-uuid-001 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
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

​
id
string
required
UUID of the invoice to update.

​
Request body

All fields are optional.
​
notes
string | null
Updated internal notes. Pass null to clear.
​
customerNotes
string | null
Updated customer-facing notes. Pass null to clear.
​
dueDate
string | null
Updated due date (YYYY-MM-DD). Pass null to clear.
​
customFields
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."
  }'