Skip to content

Invoices & Payments

Available to: Owner, Accounting, Project Manager (view only)

Invoices are created once a job reaches Completed / Needs Invoice status. They represent the formal billing document sent to the client and track payments received against the total amount owed.

One Invoice Per Job

Each job may have exactly one invoice.

Attempting to create a second invoice for a job will be rejected by the API. If an invoice needs to be corrected, it must be edited — not replaced.

Invoice Fields

Field Description
invoice_number Auto-generated at creation. Format: INV-YYYYMMDD-HHMMSS (e.g. INV-20240415-143022). Unique per tenant.
invoice_date Date the invoice was issued. Defaults to the creation date.
due_date Payment due date. Set manually or calculated from tenant payment terms.
subtotal The base amount before tax. Typically equal to the bid price.
tax_rate Pulled from CompanySettings at the time of invoice creation. Stored on the invoice for historical accuracy.
tax_amount Computed: subtotal × tax_rate.
total_amount Computed: subtotal + tax_amount.
amount_paid Running total of all payments recorded against this invoice.
balance_due Computed: total_amount − amount_paid.
status Current state of the invoice. See status machine below.

Tax applicability is determined on the originating bid (taxable field). If taxable is false, tax_rate is stored as 0 and no tax is calculated.

Tax Calculation

Tax rates are configured at the tenant level in CompanySettings.tax_rate.

When an invoice is created:

  1. The system reads CompanySettings.tax_rate for the current tenant.
  2. The rate is copied onto the invoice at creation time.
  3. Future changes to CompanySettings.tax_rate do not affect existing invoices.

This ensures historical accuracy — the tax rate applied to an invoice is fixed at the moment of creation.

Status Machine

Status Description Who Can Set
Invoice Submitted Invoice has been created and sent to the client. Accounting, Owner
Partially Paid One or more payments recorded; balance still outstanding. System (auto, on payment)
Paid Full balance has been paid. balance_due is zero. System (auto, on payment)
Workflow Complete Invoice is fully resolved and the job workflow is closed. Owner or Accounting (Close Invoice) 
Invoice Submitted → Partially Paid (on first partial payment)
                 → Paid (if full payment recorded in one entry)
Partially Paid   → Paid (on final payment)
Paid             → Workflow Complete (Close Invoice)

After Invoice Submitted, Paid is system-driven from payment totals. Workflow Complete requires Close Invoice.

Payment Tracking

A single invoice can have multiple payments recorded against it (partial payments are fully supported).

Payment Fields

Field Description
amount Dollar amount of this payment.
payment_date Date the payment was received.
payment_method How payment was made (e.g. check, ACH, wire, credit card). Free text.
notes Optional notes about this payment (e.g. check number, reference ID).

How Payments Work

  1. Accounting or Owner records a payment against an invoice.
  2. amount_paid on the invoice is updated to the sum of all payments.
  3. balance_due is recomputed.
  4. If balance_due reaches zero, the invoice status automatically transitions to Paid. Owner or Accounting then clicks Close Invoice to set Workflow Complete.
  5. All payment records are preserved — payments are never deleted or edited once recorded.

Record partial payments as they are received. The system will automatically track progress toward the full balance.

Invoice List View

The invoices list displays the following columns:

Invoice # | Client | Status | Total | Balance Due | Due Date

Click a column header to sort by that column. Click again to reverse the order. Status filters and search still apply.

Due dates are color-coded by status:

  • Green — paid or workflow complete
  • Yellow — due soon (within configured threshold)
  • Red — overdue

Role Access

Action Owner Accounting PM Supervisor Badge Worker
Create invoice Yes Yes No No No
Edit invoice Yes Yes No No No
Record payment Yes Yes No No No
View invoice Yes Yes Yes No No
View payment history Yes Yes Yes No No

Invoice edits are tracked in the ActivityLog under action type invoice_edit. The log captures a JSON diff of the fields changed.