wanderbooks/crates/ledger-mcp/handbook/invoices-and-bills.md

Invoices and bills

An invoice bills a customer: it posts Dr Accounts Receivable and Cr the revenue its lines name. A bill is a vendor's invoice to us: it posts Dr the expense or asset its lines name, and Cr Accounts Payable. A document's own figures are read from the ledger lines tagged with it, never kept on the document: a reversed payment, a void or a write-off comes out right without another copy to correct (B-38).

1. Send an invoice

• The books never send mail, and never say they did. To send an invoice, create and post it (books.create_invoice), hand its PDF to the human (books.document with pdf: true), and let the owner or a delegate send it.
• Then record the send with books.mark_sent: the invoice (invoice:7), the day it went out, who sent it (by: the owner, or the agent acting for them), how (via: email, or mail, portal, hand, or another channel's own name), to whom (to: the bill-to email, else the customer's email), whether it was the original or a reminder (kind: original for the first send, reminder after), and the channel's own reference when there is one (a message id).
• A send changes no figure and never moves the due date. Several sends are allowed: each is recorded in order, and books.documents shows the latest as last_sent.
• A void invoice can't be marked sent: it should never have reached the customer. An invoice already open, partly paid, paid or written off can (a copy for the customer's records, a reminder).

2. Record a customer payment

• Ask for the date the money arrived, where it landed, and what it paid. One deposit may settle several invoices of the same customer: pass applications with each invoice and its cash amount.
• Record how it moved (instrument) and the processor's or bank's reference. The books record payments; they never collect them.
• If the customer paid more than the invoices owe, the payment is refused: record the excess as a plain entry to 2300 Customer Deposits (no role) and apply it when the work is invoiced (D-49, A-12).
• A check or note marked "paid in full" of a disputed amount earns the UCC §3-311 warning. Record only the payment; a lawyer or the payer's agreement settles the rest.

3. Pay a vendor bill

• Ask for the date, the account it left, and which bills it pays. One payment may settle several bills of one vendor (applications).
• Record the method and the reference. A card payment is tagged as card and stays out of 1099-NEC (D-40).
• Use books.bills_due for what is due and when, with each vendor's early-payment discount window.

Taking an early-payment discount

• A bill on "2/10 net 30" takes 2% off if paid within ten days. Pass the discount beside the cash (discount); the books post the gross method: the bill is credited in full, the discount goes to Purchase Discounts (6995), and the bank gets the rest.
• A discount at most the terms allow and dated on or before their discount date needs no reason. A larger or later one needs discount_reason (a vendor who honours it anyway); it is journaled.
• A bill with an asset or prepaid line refuses a discount: record the bill net of the discount, or reclassify with an entry Dr 6995 Purchase Discounts / Cr the asset account (D-49). Never split the discount across the asset lines.

4. Void, write off, or reverse

One of these, and only one, fits what happened:

• Void it (books.void_document) when the document should never have existed: a duplicate, the wrong customer or vendor, a test entry. It is reversed, keeps its id (and, once numbered, its number) and reads void; nothing is deleted. Refused while a payment stands on it: reverse that payment first, and the refusal names it. Use a void for a mistake, never for an invoice that was real.
• Write it off (books.write_off_invoice) when the invoice was real and the work or goods went out, but the customer will not or cannot pay. That is a bad debt: the books post Dr Bad Debt Expense 6990 / Cr Accounts Receivable for what will not be collected, and what it owes falls from that day. The evidence of worthlessness — the collection letters, the bankruptcy or liquidation notice, the collection agency's report — is filed with the write-off in the same call (upload_id, or an existing_attachment_id already filed), because a bad debt is deducted on all the pertinent evidence (Treas. Reg. §1.166-2(a)). Write off all of it, or part of it with amount: a partial write-off is deductible to the extent charged off (Treas. Reg. §1.166-3(a)), and the rest stays owed and in the aging. The books must be on the accrual basis: a cash-basis company never counted the invoice as income, so there is no basis to deduct (IRC §166; Treas. Reg. §1.166-1(e)), and the tool refuses.
• Reverse an entry (books.reverse_entry) when a posted entry is wrong: a payment against the wrong invoice, a wrong amount, a check that bounced, a write-off made too soon. Posted is forever: the correction is an opposite entry linked to the one it reverses, never an edit and never a delete. Reversing a payment puts the invoice back to owing what it did; reversing a write-off re-instates the debt.

A bill is never written off: a vendor releases you with a vendor credit or by voiding its own invoice, and until then you owe it (ASC 405-20-40-1). If a vendor's bill was wrong, ask for a corrected bill or record a credit when one is built; void it only when it should never have been entered.

Recovering a debt written off

• The same tax year: reverse the write-off — books.reverse_entry on the write-off's entry. The invoice reopens, owing exactly what the write-off took off; then record the payment with books.receive_payment as usual. Nothing else is needed: within the year the deduction comes back out, and the payment is a payment.
• A later tax year: do not reverse the write-off. Record a plain entry — books.draft_entry, books.add_line on each side, books.post_entry — debiting the deposit account and crediting a "Bad debt recoveries" revenue account (tax category other income), with a memo naming the invoice. The invoice stays written off, and the recovery is income in the year it arrives (IRC §111); the CPA sees it apart from the year's sales.

Neither procedure invents a new kind of movement on the document: the books record what happened, and the invoice's timeline shows the write-off (and, if it was reversed, that it no longer stands).

5. A processor's fee

• The books never charge or collect; a processor does, and keeps a fee. Pass fee on books.receive_payment (amount, and optionally the expense account and the processor's vendor).
• The entry is gross: Dr the deposit account the net, Dr the processing-fee expense the fee, Cr Accounts Receivable the gross (A-4). Only cash movements count toward a 1099, so the fee is not a payment to the processor.

A replacement payment arrives before a bounce is known

1. Park it: a plain entry Dr the bank / Cr 2300 Customer Deposits (no role), described with the customer and what it is for.
2. When the first payment bounces, reverse it (books.reverse_entry) dated the bounce day; it un-pays its invoices.
3. Apply the parked money with books.receive_payment, deposit_to: "2300", dated on or after the bounce, against the invoices it pays. The 2300 balance returns to zero.

What the CPA will check

The agings tie to 1200 and 2000 at month and year end (they do by construction: the control check says so). Every write-off carries its reason and its evidence of collection efforts. Write-offs are not used in place of a credit memo for a valid invoice, and never to hide a mistake that a void would show. Whether a debt is worthless, and in which year, is a tax judgment that stays with the CPA: the books flag each write-off made this year in Needs attention, with the evidence beside it, until the year ends.

The evidence rule

Every entry needs its receipt ({evidence_rule}). A document the books post themselves — an invoice, a bill, a payment, a write-off — carries its own: the issued copy, the vendor's bill, the payment's reference, the evidence of worthlessness. A reversal needs none of its own: its original carries it.