The situation
Some jobs get paid the old way. You print the invoice, take it to the counter, and walk out with cash. Nothing was emailed and nothing was clicked, but the money is real and the books need to know.
A draft invoice cannot take a payment
This is the step people trip on. propose_record_payment requires the invoice to be sent, partially_paid, overdue or disputed. A draft invoice is rejected — a draft has not been issued, so there is nothing yet for a payment to settle.
Issue it first through the normal chain (propose_send_invoice → confirm_pending_operation → approve_send_invoice). The invoice transitions to sent and the audit trail is intact.
Check the recipients array before you approve. You are issuing a document the client already holds on paper; a duplicate email may be unnecessary or confusing. If the resolved recipient is an internal address, the send transitions state without reaching the client, which is what you want here. If it resolves to the client, decide deliberately whether a second copy in their inbox helps.
Record the cash
propose_record_payment(
invoice_id,
amount_cents,
payment_date: "YYYY-MM-DD", // the day you were actually paid
payment_method: "cash",
paid_on_site: true,
notes: "..."
)
approve_record_payment(operation_id, confirmed: true)
paid_on_site: true marks it as cash collected at the job rather than a banked receipt, which keeps it distinguishable during reconciliation.
Two optional guards worth using: expected_invoice_total_cents asserts against the invoice total and fails loudly on a stale figure, and external_reference gives you idempotency — re-recording with the same reference returns the existing payment instead of creating a duplicate.
The propose leg returns its reasoning before anything is written: will_transition_to, outstanding_before_cents, allocation_cents, overpayment_overflow_cents, and the list of gate_checks_passed. Read it. An overpayment does not fail — the excess mints a client credit.
Date it when the money moved, not when you typed it
Finance Engine Principle 3: real-world financial event dates are entered explicitly and never default to today. Cash taken yesterday and entered this morning is dated yesterday. payment_date is required for exactly this reason — there is no default to fall back on.
Get this wrong and the payment lands in the wrong reporting period, which surfaces later as a reconciliation difference nobody can explain.
record_payment or mark_invoice_paid?
Both end with the invoice reading paid. They are not interchangeable.
record_payment (propose + approve) | mark_invoice_paid | |
|---|---|---|
| Use for | Money you actually received | Paper-only reconciliation with no separate payment record |
| Creates | A real payment row + allocation | A synthetic reconciling payment row |
| Handles | Partial payments, overpayment → credit | Full settlement only |
| Emits | payment.recorded + invoice.paid | invoice.paid |
record_payment is the canonical path — use it by default, including for cash.
The trap with mark_invoice_paid is double-counting. It writes its own synthetic payment. If the same receipt is later imported from an external ledger, you now hold two payments against one invoice. Reserve it for receipts that will genuinely never arrive from anywhere else: a hand-reconciled cheque, a payment predating the system.
Verify
Re-read with get_invoice and assert two things, not one:
status: "paid"outstanding_cents: 0
Status alone can be misleading if allocations went sideways. The outstanding figure is refund-aware and credit-aware, so it is the number that tells the truth.
Any linked contractor payables cascade asynchronously once the invoice is paid.