Appearance
SPEC-006: Outstanding payments
Amended 2026-10-30 by ADR 0043 (Product Owner): creating sales invoices and bills from chat is now SPEC-019, approved in the card. The "Out of scope" bullet below on creating invoices and bills is superseded for creating only; editing, voiding, deleting and credit notes stay out.
Amended 2026-11-04 by ADR 0045 (Product Owner, QD-49): S19 adds a read-only table of the aged balances inside Claude, beside
payments_aged's summary, as the MCP Apps pilot. It shows only cells code built for the summary and calls no tool.
Business intent
The owner can't see at a glance which customers owe money, how late they are, or which supplier bills are waiting, and a payment that has arrived is often left unmatched to its invoice, so the invoice looks unpaid and the customer gets chased by mistake. GetMy Books lists every open invoice and bill by age, matches money that has arrived or left to the invoice or bill it settles, and, with the owner's confirmation, marks it paid in Xero. It then gives a chase list of what is really overdue. Moves SM-2 (cash collected sooner is money not lost to late payers) and protects the reconciliation work in SPEC-003.
User story
When I sit down to look at cash, I want to see who owes me and whom I owe, oldest first, with payments that have already arrived matched to their invoices, so I only chase what is really unpaid and can mark the rest paid in a couple of confirmations.
Scope
- Aged debtors and creditors. Every open sales invoice (ACCREC) and bill (ACCPAY) with an amount still due, per entity, grouped by contact and aged by due date into: not yet due, 1–30, 31–60, 61–90 and over 90 days overdue. Europe/London dates. Credit notes with an unallocated balance are listed against their contact. Totals per bucket and per contact, in pence, with the currency code.
- Match payment to invoice or bill. For money in (bank lines or Xero receive-money records, from SPEC-003's sources) and money out, find open invoices or bills it could settle. A pure, fully unit-tested matching function in
src/rules/ranks candidates on amount due (exact, or the sum of several invoices from one contact), contact name, invoice number in the bank reference, and date. One clear candidate is a proposed match; two or more, a part payment, or an overpayment is flagged for the owner and never picked. - Mark paid, preview then confirm by ID (M4).
payments_previewbuilds the Xero payments for the matches the owner chose, stores the preview and returns its ID and exactly what will be written.payments_confirmtakes only that ID, re-checks each invoice is still open with the same amount due, and creates the payments in Xero with an Idempotency-Key. A preview expires and can be confirmed once. - Audited. Every payment written, or refused, is logged in
ledger_writewith who asked, what, when, and the invoice's amount due before and after (M6). - Chase list. Overdue sales invoices after matching, per contact: amount overdue, oldest due date, days overdue, invoice numbers, and the contact's email address from Xero. For each contact it drafts a chase message (from code-built figures and a fixed template) for the owner to copy and send themselves. GetMy Books never emails, messages or otherwise contacts a customer (QD-19).
- Which bank account. Each payment names the Xero bank account it is posted to. By default it is the account the matched money arrived in or left from; the owner can choose another active bank account of that entity, and the preview shows which. An account that isn't an active Xero bank account of the entity is refused.
Out of scope
- Sending chase emails or letters to customers (QD-19 recommends not in v1).
- Paying suppliers: no payment initiation (
docs/not-doing.md). "Mark paid" records in Xero a payment that has already happened in the bank. - Creating, editing, voiding or deleting invoices, bills or credit notes.
- Allocating credit notes, or creating overpayments or prepayments. Credit notes are listed and taken into account; nothing is allocated.
- Batch payments. Foreign-currency payments: a foreign-currency invoice is listed and matched, but marking it paid is refused with a plain reason until a later slice.
- Reconciling in Xero: the owner still presses OK in Reconcile (ADR 0013).
Data model sketch
write_preview(from M4):id,entity_id,principal_id,kind(payments), the exact payload,expires_at,confirmed_at. Under RLS.ledger_write(M6): one row per payment, withbefore(amount due) andafter(amount due and the Xero payment ID).- Nothing else stored: invoices and bills are read from Xero each time.
Integration sketch
| Xero call | Purpose | Scope |
|---|---|---|
GET /Invoices?Statuses=AUTHORISED (paged, page and pageSize) | Open invoices and bills, amount due, due date, currency | accounting.invoices.read (held) |
GET /CreditNotes?where=Status=="AUTHORISED" | Unallocated credit | accounting.invoices.read (held) |
GET /Contacts/{id} | Chase list email address | accounting.contacts.read (held) |
GET /BankTransactions, bank lines from SPEC-003 | Money in and out to match | accounting.banktransactions (held) |
PUT /Payments with Idempotency-Key | Mark an invoice or bill paid | accounting.payments (new, write) |
The only new scope is accounting.payments (write, replacing accounting.payments.read; Xero's write scopes include read). Each entity reconnects Xero once to grant it. Pagination on every list call (audit X4). 429s honour Retry-After.
Scope names checked 2026-09-29. accounting.payments covers payments, batch payments, overpayments and prepayments under Xero's granular scopes, which apply to apps created from 2 March 2026 and must be adopted by existing apps by September 2027. Sources: Xero's Granular Scopes FAQ (developer.xero.com/faq/granular-scopes) for the dates; Apideck, "Xero Scopes: What Changed" (updated 11 Apr 2026) and Databuzz, "Changes to Xero Accounting API Scopes" (updated 30 Jun 2026) for the names and coverage. Xero's own scope list (developer.xero.com/documentation/guides/oauth2/scopes) did not render for the automated check: reconfirm there before building. This repo already requests granular scopes (src/xero/session.ts).
MCP tools sketch
| Tool | Read or write | Returns |
|---|---|---|
payments_aged | read | Aged debtors and creditors for an entity, by contact and bucket |
payments_match | read | Proposed matches, flagged ambiguous or partial ones, and unmatched money |
payments_chase_list | read | Overdue sales invoices after matching, by contact, each with a drafted message for the owner to send |
payments_preview | write-prep (stores a preview only) | Preview ID, the exact payments and the bank account each posts to, expiry |
payments_confirm | write to Xero (destructiveHint: false, not read-only) | Payments created, refused, and why |
payments_confirm sits behind the web release gate like the other Xero writes until M4 and the auth layer are both merged (the auth layer is).
Scenarios
S1: Aged debtors by bucket
Given FEAW has open sales invoices due 10 days ago, 45 days ago and in 5 days When payments_aged runs for FEAW Then they fall in 1–30, 31–60 and not-yet-due, with totals in pence and the currency code
S2: Creditors are aged the same way
Given FEAW has open bills When payments_aged runs Then the bills are listed as creditors, by contact and bucket, separately from debtors
S3: One clear match is proposed
Given a £1,200.00 receipt from "ACME LTD" with reference "INV-0210" And one open invoice INV-0210 to Acme Ltd with £1,200.00 due When payments_match runs Then INV-0210 is proposed as the match, with the reasons (amount, contact, reference)
S4: Ambiguous matches are flagged, never picked
Given a £500.00 receipt from Acme Ltd with no invoice number And two open Acme invoices with £500.00 due each When payments_match runs Then no match is proposed; both are listed as candidates for the owner to choose
S5: Part payments and overpayments are flagged
Given a £300.00 receipt against an invoice with £500.00 due When payments_match runs Then the match is flagged "part payment, £200.00 would stay due", not proposed
S6: Several invoices settled by one payment
Given a £1,700.00 receipt from Acme Ltd And open Acme invoices of £1,200.00 and £500.00, and no other combination of Acme's open invoices adds up to £1,700.00 When payments_match runs Then the pair is proposed as one match, and any other combination that also adds up is flagged instead
S7: Preview, then confirm by ID
Given the owner chose to mark INV-0210 paid from the Starling account on 3 Sep 2026 When payments_preview runs Then nothing is written to Xero and a preview ID is returned with the exact payment When payments_confirm runs with that ID Then one payment is created in Xero, sent with an Idempotency-Key, and logged with who, when, and amount due before and after
S8: A preview is used once and expires
Given a confirmed preview When payments_confirm runs again with the same ID Then nothing is written and the reply says it was already confirmed And a preview older than its expiry is refused the same way
S9: The invoice changed since the preview
Given a preview for INV-0210 with £1,200.00 due And INV-0210 was part paid in Xero since When payments_confirm runs Then nothing is written for INV-0210 and the reply says its amount due changed
S10: Chase list shows only what is really overdue
Given an overdue invoice whose payment has already arrived and is proposed as a match When payments_chase_list runs Then that invoice is left off the list and noted as "payment arrived, not yet marked paid"
S11: Companies are isolated
Given a session with access to FEAW only When WealthTechPros is requested, or a preview ID created for WealthTechPros is confirmed Then nothing is returned or written
S12: Xero failures are clean
Given Xero answers 401, 429, 5xx or times out When any tool runs Then it returns a plain-English tool error, retries 429 after Retry-After, and never writes half a batch without saying which payments were created
S13: Foreign-currency invoices are listed, not marked paid
Given an open FEAW sales invoice for AUD 2,000.00 at Xero's rate of 1.95 AUD per pound When payments_aged runs Then it is listed in AUD with its pound value, £1,025.64, and the currency code When the owner asks to mark it paid Then payments_preview refuses it with "foreign-currency payments are not supported yet"
S14: Credit notes reduce what is chased
Given Acme Ltd has a £500.00 overdue invoice and a £200.00 unallocated credit note When payments_aged and payments_chase_list run Then the credit note is listed against Acme, the net owed shows £300.00, and the chase list says the credit is not yet allocated And nothing is allocated in Xero
S15: An overpayment is flagged, never posted
Given a £1,300.00 receipt from Acme Ltd and one open Acme invoice with £1,200.00 due When payments_match runs Then the match is flagged "overpayment, £100.00 more than is due", not proposed And payments_preview refuses to pay more than the amount due
S16: Choosing the bank account
Given a receipt matched to INV-0210 that arrived in the Starling account When payments_preview runs without naming an account Then the payment posts to Starling, and the preview says so When the owner names FEAW's Amex account instead Then the preview posts to Amex and says so When the owner names an account that isn't one of FEAW's active Xero bank accounts Then the preview is refused, naming the accounts that can be used
S17: The chase list never contacts a customer
Given overdue invoices for Acme Ltd When payments_chase_list runs Then it returns a drafted message for the owner to send, with the invoice numbers, amounts and due dates from code And no email or message is sent to Acme by GetMy Books
S18: Only credit notes left is said plainly (approved 2026-10-06 by the Product Owner, pre-sale review)
Given no unpaid invoices for FEAW, but a £200.00 unused credit note to Acme Ltd When payments_aged runs Then the heading says nothing is owed to FEAW and names the £200.00 in unused credit notes, never "owed to you £0.00 by 0 customers" And the same holds for unused supplier credit notes when there are no unpaid bills
S19: The aged balances as a table inside Claude (approved 2026-11-04 by the Product Owner, ADR 0045, QD-49, issue #99)
A read-only view (MCP Apps) beside payments_aged's summary, in clients that can show one (Claude Desktop, claude.ai). It is a pilot: the only view of books data, under ADR 0045's limits.
Given FEAW with unpaid invoices from Acme Ltd and Oz Pty and an unpaid bill from Supplier Ltd When payments_aged runs in a client that shows MCP Apps views Then the reply is the same summary text as before, and Claude Code and any client without views lose nothing And the client shows a table for what is owed to FEAW and one for what FEAW owes, one row per contact and a Total row, under the summary's headings And every cell is a string GetMy Books' code built in src/present/ for the summary: the view works out no figure, total, rounding or conversion of its own, so each cell equals the summary's table cell for the same contact and column And the owner can sort the rows by any column (money by its value in pence from the tool's data), with the Total row kept last And the view has no button that calls a tool, sends no message and puts nothing in Claude's context And it loads no outside script, style, font or image: its page is one file with the pinned MCP Apps bundle inlined, as the approval card's is
Edge cases
- Invoices in a foreign currency: listed and matched in the invoice currency with the pound value at Xero's rate; marking paid refused (out of scope).
- A receipt that matches an invoice already marked paid in Xero: shown as "Xero already has this payment; reconcile it", never paid twice.
- Draft and submitted (unapproved) invoices are not outstanding.
- Contact names differ between the bank and Xero ("ACME LTD" vs "Acme Limited"): normalised the same way as SPEC-003 S17.
Dependencies
- M4 (preview then confirm by ID, the
write_previewtable). - ADR 0021 accepted (payments against invoices from chat), QD-18.
- The
accounting.paymentsscope and one Xero reconnect per entity. - SPEC-003's bank line sources for money in and out.
Exit test
On FEAW's real data, the aged debtors and creditors totals equal Xero's Aged Receivables and Aged Payables summary reports on the same date, to the penny. The Product Owner then marks one real matched payment paid through preview and confirm, and Xero shows the invoice paid and the payment in the bank account ready to reconcile.
S19 (ADR 0045's pilot): the Product Owner opens payments_aged for FEAW in Claude Desktop and on claude.ai, and the table's figures match the text summary one for one, and no raw JSON is shown beside the table. The outcome is recorded in ADR 0045. If the JSON text block does show beside the table, raise a SPEC-011 amendment (the S9 pattern, issue #303) rather than dropping the JSON here: Claude uses it to answer follow-up questions.
Validation
| id | name | rule | assert |
|---|---|---|---|
| V1 | Buckets | Days overdue counted from the due date in Europe/London; 0 days is not yet due | S1, S2 |
| V2 | No guess | A match is proposed only when exactly one candidate set fits | S3–S6 |
| V3 | One write per preview | A preview ID confirms once, before expiry, with the invoice unchanged | S7–S9 |
| V4 | Never more than due | A payment never exceeds the amount due; overpayments are flagged | S5, S15 |
| V5 | No outbound contact | Nothing in SPEC-006 sends to a customer | S17 |
| V6 | Shown, not worked out | A view of the aged balances shows only cells code built for the summary, and calls no tool | S19 |