Appearance
0043: Sales invoices and bills created from chat, previewed and approved in the card
Context
GetMy Books reads Xero and, with the owner's Approve in the approval card, enters missing bank lines (ADR 0016), posts VAT correction journals (ADR 0017) and attaches receipts (ADR 0022, 0031). It cannot create a sales invoice or a bill. On 2026-10-30 Rob Duncan reported two real cases: a GBP 29.00 airport lounge cost paid by FEAW and recharged to Wealth Tech Professionals Limited, and a GBP 372.20 British Airways flight he paid for personally that WEALTH TECH PROFESSIONALS LIMITED must reimburse. Both had to be keyed into Xero by hand.
What stands in the way today:
- ADR 0016 point 5: "Create only: no edits, deletes, payments against invoices, or anything touching VAT returns", and point 1, which limits creation to bank lines the reconciliation check classifies as missing.
- SPEC-006 "Out of scope: Creating, editing, voiding or deleting invoices, bills or credit notes".
docs/not-doing.mdrow "Bookkeeping entry or receipt capture", which says entering the books is not in scope and creating records from receipts stays out (ADR 0022 point 2).- The Xero app requests
accounting.invoices.readonly.
A competitor (the Meridian connector, docs/research/meridian-connector-for-xero-2026-10-30.md) already lets Claude create invoices and bills in Xero, with no approval step. GetMy Books' difference is the card: nothing is written until the owner presses Approve, and every figure the card shows is worked out by code.
Decision
Accepted by the Product Owner on 2026-10-30:
One tool, one document per card.
invoice_create_previewmay create one Xero sales invoice (ACCREC) or one bill (ACCPAY) per approval card, asDRAFTby default orSUBMITTED(awaiting approval in Xero) when the owner asks, neverAUTHORISED, never paid, never sent. This extends the writes ADR 0016 permits, for SPEC-019 only. ADR 0016 points 3 to 6 apply unchanged: preview first, the owner's Approve in the card makes the write, create only, every write logged inledger_write, no filing.Every figure comes from the owner, worked out by code. The call carries what the owner said: contact name, dates, reference, and per line a description, quantity, unit price in pounds and pence, account code and tax type. Code turns those into integer pence: net, VAT at the Xero tax rate's effective rate, and gross, per line and in total. Nothing is read from a receipt into the document: ADR 0022 point 2 stands. Figures a language model reads from a receipt remain search terms.
A receipt is evidence, attached in the same card. A file in the company's Xero Files inbox may be named with the document; it is checked at preview and again at Approve as SPEC-003 S34 does for a bank entry, and linked to the created document after it is made (ADR 0022 point 1, ADR 0031 point 4).
The contact is looked up, never created. The name is matched against the company's Xero contacts, case-insensitive, whole name. Exactly one active match is used, by
ContactID; no match or more than one is refused with the candidates named. Writing a bare contact name would let Xero create a near-duplicate (FEAW already has "WealthTechPros" and "Wealth Tech Professionals Limited"), so the document always carries the ID. GetMy Books creates no contacts.Chart, tax rate, side and lock dates are checked by code. The account code must exist, be active and not be a bank account; the tax type must be an active Xero tax rate on the document's side (sales or purchase); a code whose Xero default tax type differs from the line's is a warning the card shows, not a refusal (FEAW's travel accounts default to No VAT). A document dated on or before a Xero lock date is refused at preview and again at Approve (AUDIT C5).
Once per card. The Idempotency-Key scope is the preview ID, so a retry of the same card is not duplicated and the same document asked for again in a new card is still created once per card. Approve re-plans and refuses if the chart, tax rates, contact or lock dates changed since the preview.
What this supersedes and what stands. SPEC-006's exclusion is superseded for creating invoices and bills only: editing, voiding, deleting, credit notes, repeating invoices, sending to the customer and allocating payments stay out (payments are ADR 0021).
docs/not-doing.mdrow "Bookkeeping entry or receipt capture" is reworded: entering a sales invoice or bill the owner dictates is in scope (SPEC-019); creating a record from a receipt's figures stays out.Paid personally by a director. A bill for a cost a director paid personally is addressed to the director's own Xero contact and left awaiting payment. How it is settled (reimbursement, a Directors' Loan Account journal, an expense claims account) is QD-46 and a later slice (issue #306); nothing about settlement is guessed.
Amended 2026-11-04 (#335; QD-46, decided by the Product Owner on 2026-11-04, recorded in
docs/sge/questions.mdby PR #359). A bill a director paid personally is settled against the company's Directors' Loan Account (Xero's UK default is code 835), approved in the card; the company's accountant confirms this per company. The same card creates the billAUTHORISED(Xero takes a payment only against an approved bill) and then makes one Xero payment of its whole total from that account, dated the bill's date. This is the one exception to point 1's "neverAUTHORISED, never paid", and to point 7's payments staying out, for director-paid bills only. The account is the one the owner names, or the one active liability account whose name contains "Director" and "Loan"; none or several is refused, and no account is created. Xero needs "Enable payments to this account" ticked on it (EnablePaymentsToAccount); without it the preview is refused with that instruction. A payment that fails leaves the bill made and awaiting payment, and the outcome says so. The Xero app asks foraccounting.payments(write) in place ofaccounting.payments.read, so each company reconnects once. Reimbursement from the bank and expense claims accounts stay out. SPEC-019 S13, S17 and S20 to S23.
Consequences
- The Xero app requests
accounting.invoices(write; Xero's write scopes include read) in place ofaccounting.invoices.read. Each company reconnects Xero once (owner action after deploy; confirm the scope name in the Xero developer portal first, as QD-37 did). - AUDIT X2's evidence changes: scopes are read-only except bank transactions, manual journals, files and now invoices.
- Worst case: a wrong draft document. It is visible in the activity log and
ledger_write, carries no VAT effect until the owner approves it in Xero, and the owner deletes a draft in Xero; GetMy Books does not delete it. - A new capability CAP-02.14 "Invoices and bills (created from chat)" joins the MVP (capability model 1.11.0), governed by SPEC-019.
tests/mcp/tools.test.tsgains a fifth Xero-writing tool; no tool name contains submit or approve (ADR 0005).