Customer Invoices & Payments

A customer invoice is the formal request for payment you send to a customer. It carries a list of line items (what was sold and for how much), an optional tax rate, and a running payment history that tracks every dollar received until the balance reaches zero. Invoices can be created manually or generated directly from a sales order, and they move through a clear status lifecycle so you always know what is outstanding, overdue, or closed.

Invoices and the payments against them are separate records — deleting or voiding an invoice soft-deletes it but the underlying payment records are retained for audit purposes.

Creating an invoice #

New invoices are created from Sales → Invoices → New Invoice. A handful of fields drive most of the behavior:

• Customer — required. Selecting a customer enables the Sales Order field and pre-loads any payment terms set on that customer's record (Net 15, Net 30, etc.), which automatically computes the Due Date from the invoice date.
• Sales Order — optional link to an existing sales order. Scoped to the selected customer.
• Invoice # — auto-generated as INV-0001, INV-0002, and so on, but you can override it with your own numbering scheme.
• Status — starts as Draft; see Invoice statuses below.
• Invoice Date and Due Date — both optional; if you set an invoice date and the customer has payment terms, the due date is filled in automatically.
• Tax Rate — choose from your configured tax rates. Changing the rate recalculates amount_due and tax_amount immediately using the current line-item subtotal.
• Notes — free-form memo printed on or shared with the invoice.
• Amount Due — read-only display; always the sum of line-item totals plus tax.
• Custom fields — any extra attributes defined for invoices appear at the bottom of the form.

Invoice statuses #

An invoice is always in exactly one of six statuses, shown as a badge in the list:

• Draft — created but not yet sent; the default.
• Sent — issued to the customer; can become Overdue automatically.
• Partially Paid — at least one payment has been recorded, but the balance is not yet zero.
• Paid — amount_paid equals or exceeds amount_due; set automatically when the last payment clears the balance.
• Overdue — a Sent or Partially Paid invoice whose due date is in the past. Status is checked and updated automatically.
• Voided — cancelled; once voided the status is locked and no further payments can be applied.

Statuses transition automatically based on payments and dates. You can also set the status manually (e.g. to mark Sent after emailing the invoice), with one exception: Voided is permanent.

Line items #

The Line Items tab on an invoice's page is where you add, edit, and remove what is being charged. Each line item carries:

• Description — a free-text label for the line (required if no Product is chosen).
• Product — optional link to an Product. When set, the Product's name appears in the description placeholder.
• Quantity — numeric, supports decimals (e.g. 2.5 hours, 0.75 lb).
• Unit Price — entered in dollars in the UI; stored and returned in cents over the API (5000 = $50.00).
• Notes — per-line memo.

The line total is quantity × unit_price. Adding or removing a line item triggers an immediate recalculation of the invoice's amount_due and tax_amount.

Recording payments #

Record a payment right from the invoice's view page with the Record Payment action — enter the amount, payment date, method, an optional reference number, and notes. The Record Payment button is only available once the invoice has been sent (it is hidden on Draft and Voided invoices). The Payment History tab then lists every payment received against the invoice, showing each one's date, amount, method, reference number, and any notes. That tab is read-only — you add payments through the Record Payment button (or the API, see below), not by editing the list.

Payment methods are: Cash, Check, Credit Card, Bank Transfer, and Other. A payment's amount must not exceed the invoice's remaining balance; attempting to over-pay returns a 422 validation error. When the balance hits zero the invoice status moves to Paid automatically.

Amount remaining is amount_due − amount_paid. The API exposes both fields as integers in cents so you can always compute the outstanding balance without rounding surprises.

The invoice list #

The invoice list (Sales → Invoices) shows each invoice's Invoice #, Customer, linked SO #, Status badge, Invoice Date, Due Date, and Amount. Sort by any column, search by invoice number or customer name, and use the Trashed filter to view soft-deleted records.

What lives on the invoice page #

Open any invoice to find:

• Details — the core fields (customer, dates, tax rate, notes, amount due).
• Line Items — add, edit, or remove lines; totals recalculate live.
• Payment History — a read-only log of every payment received.
• Attachments — upload a PDF copy or supporting documents.
• Change history — a full audit trail of every edit.

Relationship to sales orders and other modules #

An invoice is often the downstream output of a sales order — the SO tracks what was committed, and the invoice requests payment. The sales_order_id field on an invoice makes this link explicit. Separately, rental agreements generate their periodic invoices through the billing cycle, which also land here as standard customer invoices. Credit memos are the mechanism for issuing refunds or adjustments against a paid invoice.

Doing it from the API #

# Create an invoice for a customer
curl -X POST "https://your-domain.com/api/v1/customer-invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "<id>", "invoice_date": "2026-06-02", "status": "draft", "tax_rate_id": "<id>"}'

# Add a line item (unit_price in cents)
curl -X POST "https://your-domain.com/api/v1/customer-invoice-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_invoice_id": "<id>", "description": "Consulting", "quantity": 2, "unit_price": 15000}'

# Record a payment (amount in cents)
curl -X POST "https://your-domain.com/api/v1/customer-payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_invoice_id": "<id>", "amount": 30000, "payment_date": "2026-06-02", "payment_method": "bank_transfer"}'

All money fields — amount_due, amount_paid, tax_amount, unit_price, and payment amount — are integers in cents over the API (30000 = $300.00). The UI converts them to dollars automatically.