Reading the ledger correctly
TRUED's figures are calculated and stored by TRUED. The API hands them to you as they are. These rules explain how to add them up so your reports match TRUED to the cent.
What a client owes: net_due
An invoice carries three client figures:
| Field | Meaning |
|---|---|
gross_amount |
The total billed before credit |
credit_applied |
Client credit used on this invoice |
net_due |
What the client owes: gross_amount minus credit_applied |
Use net_due for "what is owed". Use gross_amount only when you want the value before credit.
Never add up time entries or charges to get an invoice total: an invoice can include a monthly
fee, a settlement or adjustments that are not time entries. The invoice's own figures are the
answer.
Credit notes are negative
An invoice with type: "credit_note" reduces what a client owes, and its amounts are negative.
Add it in as it is:
billed for September = sum of net_due over every invoice for 2026-09, credit notes included
credit_note.kind says what it is:
post_payment: a credit given to the client after they paid. Count it.reversalandreverse_and_rebill: this note cancels an earlier invoice.
Skip reversed pairs
When an invoice is reversed, TRUED keeps the original (with reversed: true) and adds a credit
note that cancels it. The two add up to zero. The simplest correct report leaves out both:
every invoice with reversed: true, and every credit note whose kind is reversal or
reverse_and_rebill. A re-billed invoice is a normal invoice and counts.
Prepaid packages
An invoice with type: "package" is the sale of a prepaid package of hours. Report it as a
package sold, not as billing for the period: the hours are billed against the package as they are
worked.
A zero invoice may be billed elsewhere
When billed_externally is true, the client is billed outside TRUED (for example straight in
QuickBooks), so gross_amount and net_due are zero by design. delivered_value gives the
value of the work delivered. Do not report these clients as "not billed".
Margins on a team engagement
Some engagements have several contractors but one client bill, which sits on one contractor's
invoice. On the other contractors' invoices the margin is left empty and margin_note says whose
invoice carries the bill. For that engagement's margin, use the invoice that carries the bill.
(Margin fields need the margin:read permission.)
Final figures: period_closed
While a month is open, its figures can still change: time is approved, charges are added, credit
is applied. When period_closed is true on an invoice, the month is closed and its figures are
final. Re-read open months; stop re-reading closed ones.
Statuses
client_billing_status and contractor_pay_status are stable codes:
| Code | Meaning |
|---|---|
not_ready |
Client side: work is still being reviewed |
ready_to_send |
Client side: approved, not yet sent to the client |
sent |
Client side: sent to the client |
paid |
Client side: the accounting system confirmed the client paid |
to_review |
Pay side: waiting for approval |
approved_to_pay |
Pay side: approved, not yet sent to payroll |
sent_to_payroll |
Pay side: handed to payroll. This is not proof of payment |
vaulted |
Pay side: set aside as done for the period. This is not a payment |
paid |
Pay side: the accounting system confirmed the payout |
New codes may be added later, so treat an unknown code as "in progress" rather than failing.
Payments are confirmed payments only
/v1/payments lists a payment only when your accounting system confirmed it. An invoice that was
marked by hand or set aside in TRUED is not a payment and does not appear. paid_at on an invoice
follows the same rule.
Money format
Money is a string with two decimals, for example "1234.50", next to currency. Read it as a
decimal, not a floating point number, so cents never drift.