Invoices

Period and status filter

The list is scoped to the AssetProvider's shared range, the same as the report cards, so it stays in step with the rest of the dashboard. The dateFrom and dateToprops pin a fixed window for this compound only, detaching it from the provider's range; they are both-or-neither. The resolved range becomes the endpoint's only date filter — the due-date window, due_at_start (inclusive) and due_at_end(exclusive) — so an invoice is in the list when it falls due inside the period, whenever it was raised. Both bounds are part of the query key, so changing the period re-requests. Periodrenders the window's label.

The status filter is a query parameter: the endpoint returns the invoices holding that status, and "all" clears it. All six statuses are offered, so a refunded invoice can still be found and read even though this compound cannot set that status.

An invoices override supplies rows directly, so the status filter and period are not re-applied. Supply the rows the filter and period you are demonstrating would have returned.

Statuses

Six statuses exist on the wire — open, paid, voided, uncollectible, partially_refunded and refunded. All six render on Status and all six are offered by the filter. Four of them can be set: StatusAction renders nothing for the refunded pair, which is display-only here.

A refund is not a status write. It creates a Refund object and needs its own transaction match on the way back out — the money in that clears the receivable and the money out are two opposite matches. Flipping the field alone would label an invoice refunded with no money movement behind it, which is worse than not offering it at all, so refunds wait for their own endpoints and their own flow.

uncollectible is not a plain status write either. It POSTs to the write-off endpoint with the invoice's outstanding balance, which posts its own journal entry; the other three are a plain PATCH of the status field. StatusAction picks the right one, so a consumer only names the status it wants. Either way the write reports through pendingStatusId and refetches the list on success, and a failure lands on ActionError.

A written-off invoice carries the write-off as a payment, which is why PaymentKind distinguishes it from a bank payment, and why useRowMatchedTransactions() leaves it out.

Editing: lines only

An existing invoice edits through one narrow door: its lines. The number, the customer and the dates are fixed at creation — the update endpoint has no write for them — so the editor swaps the lines for inputs and leaves everything else read.

There is no in-place line write either. The endpoint's line_changes only creates and deletes, so a modified line is replaced: its original id goes into delete_lines and the edited content into create_lines, with its category riding along. An edit that changed nothing closes without a request.

Order is held through that replacement. Lines read back in creation order, and a recreated line is the newest — replacing one alone would send it to the bottom of the list. So replacement starts at the first change and carries the rest of the list with it: every line from that point is recreated in the editor's order, only the untouched head keeps its ids, and removals on their own reorder nothing, so they only delete.

Validation mirrors the create draft: at least one described line, and no negative amounts. A line the user never described was never filled in, so it sends nothing. SaveEdit commits; a failure surfaces on EditError with the editor still open.

Creating: partial success

The create endpoint is a bulk one: the body is an array even for a single invoice, and a 200 can still carry a per-invoice failure in errors instead of throwing. Savereads the response before deciding whether it worked — the first entry in errors is raised as the failure, so the draft stays open with its message on SaveError rather than closing over an invoice that was never created.

This compound sends one invoice per request, so there is only ever one entry to read. Nothing here batches; the array is the endpoint's shape, not a feature of the surface.

Inline customer creation

An invoice needs a customer, and the customer who needs invoicing is often the one who is not in the directory yet. AddCustomerTrigger opens a sub-draft inside the invoice draft; SaveCustomer POSTs the customer, selects the new id on the invoice draft, closes the sub-draft and refetches the customer directory. Name is the only required field, matching the API, and a blank email or phone is sent as null rather than an empty string.

The sub-draft's failure is its own: CustomerError is separate from SaveError, so a customer that could not be added never reads as an invoice that could not be created. Cancelling the invoice draft discards both.

Matched transactions

A payment payload carries only a transaction_id, so the bank description behind it has to be joined on. Root does that with one query for the whole table rather than one per row: the date window is derived from the payments actually on screen, so it is bounded by the data rather than by a guessed range, and every row reads out of the same cache entry. Nothing matched anywhere in the list means no lookup at all.

useRowMatchedTransactions() is where a consumer reads the result. A description identifies a transaction in a way an amount cannot — two invoices settled by different transactions of the same value are indistinguishable by figure — and it is null while the lookup is in flight, or when the compound is running on overridden rows that do not supply one. Fall back to the amount rather than rendering a blank.

This lookup is what the matching surface reads its descriptions from too, which is why a settled invoice can name what paid it without the panel fetching anything. See Matching.

Matching

Attaching a bank transaction to an invoice is TransactionMatch — one compound serving both sides of the ledger, because Invoices and Bills want the same guarantees and a second copy is exactly where a wrong-match bug would appear. This compound's part in it is two: the trigger that gets the user there, and the payments the surface is given to work from.

MatchTrigger expands the row, which is where the surface is mounted, and renders nothing once the row has nothing left to match. That test is useRowNeedsMatch(): money still outstanding, and a status that can still take a payment. A voided or written-off invoice is closed as far as money is concerned, so offering to match one would invite booking a payment against a document that no longer stands. A host that wants an affordance in the trigger's place on a settled row reads the same hook and renders ViewTrigger instead.

Mount TransactionMatch.Root inside Detail or Viewer with kind="invoice", the row's id, its totalDue as outstanding, its dueAt, and useRowMatchedTransactions() as matched. Passing the payments in is what lets the surface offer to detach one and name it — a settled invoice runs no candidate query, so those descriptions are the only ones it has. A successful match invalidates this list, so the balance and the Transactions column move on their own.

Which invoices can take a match, and what happens when a transaction is worth more than the balance, are the matching compound's decisions rather than this one's. The attach request leaves allocation to the API: it settles the invoice and posts excess transaction value to customer credit — see Guardrails.