Skip to content

SPEC-019: Invoices and bills ​

Amended 2026-11-04 (issue #335; QD-46 decided by the Product Owner on 2026-11-04, ADR 0043 note of that date): a bill a director paid personally is settled against the company's Directors' Loan Account in the same card. Scope (the paid-personally bullets), S13, S17, Out of scope, the integration sketch and V7 are aligned; S20 to S23 and V9 are new.

Business intent ​

GetMy Books can read Xero and, after the owner's Approve, enter bank lines, post VAT corrections and attach receipts, but it cannot create a sales invoice or a bill. Recharging a cost to another company, or recording a supplier bill the owner paid personally, means keying it into Xero by hand. Worked examples from 2026-10-30: a GBP 29.00 airport lounge cost paid by FEAW on its Amex and recharged to Wealth Tech Professionals Limited (GBP 24.17 net, GBP 4.83 VAT at 20%); a GBP 372.20 British Airways flight Rob Duncan paid for personally for WEALTH TECH PROFESSIONALS LIMITED. Moves SM-2.

User story ​

When I need a sales invoice or a bill in Xero, I want to say who, when, what and how much, see exactly the document that would be created with its net, VAT and total worked out by code, attach the receipt in the same step, and have it created as a draft only when I press Approve.

Scope ​

  • One tool, invoice_create_preview, with type: "sales" | "bill". Inputs: the company; the contact's exact Xero name; the document date and due date; an optional reference; amountsAre: "exclusive" | "inclusive" (default exclusive); one to 25 lines, each with a description, a quantity (up to four decimal places, more than zero), a unit price in pounds and pence, an account code and a tax type, and an optional reason for the activity log; an optional status: "draft" | "awaiting_approval" (default draft); an optional receipt fileId from receipts_inbox (slice 2, issue #305); for a bill, paidBy: "company" | "director" (default company; slice 3, issue #306), with directorName, the director's own Xero contact name, which must be the contact, and an optional settleAccountCode (slice 4, issue #335). Slice 1 (#308) left fileId and paidBy out of the tool's schema; slices 2 and 3 add them. A bill's reference is sent to Xero as its InvoiceNumber, which Xero shows as the bill's Reference; Xero's Reference field is for sales invoices only.
  • Figures by code (integer pence). Unit price text is parsed with parseAmountToPence (two decimal places, refused otherwise). Per line, with amountsAre: exclusive: net = round(quantity x unit pence), VAT = round half up of net x rate / 100, gross = net + VAT; with inclusive: gross = round(quantity x unit pence), VAT = round half up of gross x rate / (100 + rate), net = gross - VAT. The rate is the tax type's EffectiveRate read from Xero's tax rates on every preview and Approve. Totals are sums of the lines. The card says Xero's own rounding is authoritative; the outcome shows the total Xero returned.
  • Contact lookup. GET /Contacts filtered by name; the match is whole name, case-insensitive, trimmed; exactly one ACTIVE match is used by ContactID. No match or several: refused, naming every candidate Xero offered (up to ten). No contact is ever created.
  • Chart and tax rates. From fetchLedgerAccounts and fetchTaxRates: the account code must exist, be ACTIVE and not type BANK; the tax type must be an ACTIVE rate whose side (sales or purchase, from the tax-types table or the rate's name) is the document's; a line whose tax type differs from the account's Xero default is a warning in the card.
  • Lock dates. checkLockDates on the document date at preview and at Approve (the organisation is re-read each time).
  • Receipt in the same card (slice 2, issue #305). A fileId is checked at preview (checkEntryReceipts: the file exists, is not named for another company, is linked to nothing) and at Approve (receiptNoLongerAttachable, the file read once, before the document is created); after the document is created its links are read again and it is linked with createAssociation (ObjectGroup Invoice, record kind bill or invoice) and logged as an attachment. A receipt that fails the preview check leaves the document in the card without it, with the reason. One that can no longer be attached at Approve, or whose link fails, leaves the document made; the outcome says the receipt is not attached and why, and the card says partly written.
  • Preview, card, Approve, status. The plan is stored in write_preview with kind invoice; the card shows the document; Approve runs the executor, which re-plans, refuses on any change (sameJson), creates the document with PUT /Invoices and an Idempotency-Key scoped to the preview ID, logs one ledger_write row (key invoice:<previewId>), attaches the receipt, and reports the Xero InvoiceID, InvoiceNumber, status and total. write_status reports the same afterwards.
  • Activity log (SPEC-010). The preview row holds the type, contact, dates, reference, each line (description, quantity, unit pence, account code and name, tax type, net and VAT pence by code) and the reason; the decision and outcome rows hold who, when, the Xero IDs and whether the receipt attached.
  • Paid personally by a director (bills only, slice 3). paidBy: director requires directorName, which must equal the contact (whole name, case aside), and prefixes the reference with "Paid personally: " (or makes it "Paid personally" when none is given; the reference given is then at most 238 characters, so the whole stays within 255).
  • Settled against the Directors' Loan Account (slice 4, issue #335; QD-46, decided 2026-11-04). A director-paid bill is settled in the same card: Approve creates it approved in Xero (AUTHORISED, which Xero needs before it takes a payment), then makes one Xero payment of the bill's whole total, as Xero gives it, from the company's Directors' Loan Account, dated the bill's date. The account is the one the owner names (settleAccountCode), or else the one active account in the chart whose name contains "Director" and "Loan" (case aside) and whose class is liability (Xero's UK default is 835 "Directors' Loan Account"). None, or more than one, is refused naming what was found; the account is never guessed and never created. Xero takes a payment from an account that is not a bank account only when its "Enable payments to this account" box is ticked (EnablePaymentsToAccount): the chart is read at preview and at Approve, and an account without it is refused saying what to tick in Xero. The card shows the account and the amount; the activity log keeps the account's code, name and ID and the payment's Xero ID. A payment that fails leaves the bill made, approved and awaiting payment: the outcome says it was not settled and why, and the card says partly written. A director-paid bill takes no status of awaiting approval (the card approves it). The company's accountant confirms, per company, that the Directors' Loan Account is where these bills are settled (owner action).

Out of scope ​

  • Sending an invoice to the customer; emailing anyone.
  • Credit notes, repeating invoices, prepayments, overpayments.
  • Editing, voiding, approving (AUTHORISED) or deleting a document; the owner does that in Xero (except a director-paid bill the card settles, S20).
  • Payments against the created document (SPEC-006, ADR 0021), except the one Directors' Loan Account payment of a director-paid bill (slice 4).
  • Creating contacts, accounts or tax rates.
  • Reading figures from a receipt into the document (ADR 0022 point 2).
  • Foreign-currency documents (ADR 0025): the organisation must be GBP and the document is in GBP.
  • Settling a director-paid bill by reimbursement from the bank or through an expense claims account, and settling a director-paid bill made before slice 4 (QD-46 chose the Directors' Loan Account; issue #335).

Data model sketch ​

  • write_preview kind invoice: { request: InvoiceRequest, plan: PlannedInvoice, receipt?: { file } }; bank_account_id null.
  • ledger_write: one row per created document, bank_line_idinvoice:<previewId>, entry the planned document, after the Xero InvoiceID, InvoiceNumber, Status and Total; plus the attachment row if a receipt was linked.
  • activity_log: preview, decision, outcome rows with previewKind: 'invoice'.
  • No new table, no migration.

Integration sketch ​

Xero callPurposeScope
GET /Contacts?where=Name=="..." (and a searchTerm fallback for candidates)Resolve the contact to one ContactIDaccounting.contacts.read (held)
GET /Accounts, GET /TaxRates (with EffectiveRate)Chart and rates for validation and VATaccounting.settings.read (held)
GET /OrganisationBase currency and lock datesaccounting.settings.read (held)
PUT /Invoices with Idempotency-KeyCreate the documentaccounting.invoices (write, new; replaces .read)
PUT /Payments with Idempotency-KeySettle a director-paid bill from the Directors' Loan Account (slice 4)accounting.payments (write, new; replaces .read)
GET /Invoices/{id}Read back number, status, totalaccounting.invoices
POST /files.xro/1.0/Files/{fileId}/AssociationsAttach the receiptfiles (held)

Each company reconnects once for the new scope (owner action). Confirm the scope name in the Xero developer portal before deploy (QD-37 pattern).

MCP tools sketch ​

ToolRead or writeReturns
invoice_create_previewwrite-prep (card)Preview ID, the document with net, VAT and total per line and in all, warnings, the receipt, expiry
write_status (existing)readWhat became of the preview: Xero ID, number, status

Scenarios ​

S1: Preview a sales invoice ​

Given FEAW is connected, its chart has an active sales account 200 defaulting to OUTPUT2, and Xero has exactly one active contact "Wealth Tech Professionals Limited" When invoice_create_preview runs with type sales, that contact, date 2026-10-14, due 2026-11-13, reference "Lounge recharge", one line "Airport lounge, 14 Oct 2026" quantity 1 at 24.17, account 200, tax OUTPUT2 Then nothing is written, and the card shows the contact, dates, reference, the line with net £24.17, VAT £4.83 and total £29.00, the status draft, and a preview ID that expires in 60 minutes, with its expiry time

S2: Approve creates the document once ​

Given the preview in S1 When the owner presses Approve in the card Then one PUT /Invoices is made with Type: ACCREC, Contact: { ContactID }, Status: DRAFT, LineAmountTypes: Exclusive, the line, and an Idempotency-Key scoped to the preview ID And the outcome names the Xero invoice ID, number and total, and write_status reports it as written with the same When Approve is pressed again Then nothing is written and the card says it was already decided

S3: Declined or expired writes nothing ​

Given a preview When the owner presses Decline, or 60 minutes pass Then nothing is written, write_status says declined or expired, and a new preview is needed

S4: An ambiguous contact is refused, naming the candidates ​

Given Xero has active contacts "WealthTechPros" and "Wealth Tech Professionals Limited" When the owner names "Wealth Tech" Then the preview is refused, lists both names, and says to give the exact name And when two active contacts share the exact name, the preview is refused naming both

S5: An unknown contact is refused, never created ​

Given no Xero contact matches "Acme Widgets Ltd" When the preview runs Then it is refused and says to create the contact in Xero first; no contact is created

S6: Account code and tax type are checked ​

Given a line with an archived account, a bank account, an unknown code, an inactive tax type, or a sales tax type (OUTPUT2) on a bill When the preview runs Then it is refused naming each problem and nothing is stored

S7: A default tax type that differs is a warning ​

Given FEAW's account 493 "Travel - National" defaults to NONE in Xero When a line is coded 493 with INPUT2 on a bill Then the card shows a warning naming the account's default, and the preview is not refused

S8: Lock dates refuse at preview and at Approve ​

Given the organisation's period lock date is 2026-09-30 When a document dated 2026-09-30 is previewed Then it is refused naming the lock date Given a document dated 2026-10-14 was previewed and the lock date is then moved to 2026-10-31 When the owner presses Approve Then nothing is written and the outcome names the lock date

S9: A receipt is attached in the same card (slice 2, issue #305) ​

Given a file in FEAW's Xero Files inbox linked to nothing, and a bill preview naming its fileId When the owner presses Approve Then the bill is created, then the file is linked to it with ObjectGroup Invoice, both are logged, and the outcome says attached And if the link fails the bill stays made and the outcome says the receipt is not attached and why

S10: A receipt that cannot be attached leaves the document in the card (slice 2, issue #305) ​

Given the named file is already linked to another record When the preview runs Then the document stays in the card without the receipt, the reason is shown, and Approve creates the document only

S11: The activity log holds the proposal, the decision and the outcome ​

Given a preview, an Approve and a created document When activity_log runs Then it shows who previewed the document with each line's figures by code and the reason, who approved it and when, and the Xero ID, number and status it now holds, and whether the receipt attached

S12: A bill is created the same way ​

Given type bill, contact "British Airways" (one active match), date 2026-10-14, due 2026-11-13, one line quantity 1 at 372.20, account 493, tax NONE When the owner approves Then one ACCPAY draft bill is created with the due date and the figures, and the card and outcome say "bill from British Airways"

S13: Draft by default, awaiting approval on request, never authorised ​

Given status is left out, or is awaiting_approval When the document is created Then its Xero status is DRAFT, or SUBMITTED, and no input can make it AUTHORISED, PAID or sent And the one exception is a director-paid bill, approved and settled against the Directors' Loan Account by the card (S20; amended 2026-11-04, issue #335)

S14: A non-GBP organisation is refused ​

Given an organisation whose base currency is not GBP When the preview runs Then it is refused as every money tool does (ADR 0025)

S15: Figures are worked out by code, inclusive or exclusive ​

Given one line quantity 3 at 10.00 with a 20% rate When amountsAre is exclusive Then net £30.00, VAT £6.00, total £36.00 When amountsAre is inclusive Then total £30.00, VAT £5.00, net £25.00 And a rate the tax rates do not give is refused, never guessed

S16: Text and numbers are checked before anything is stored ​

Given a description over 200 characters, a reference over 255, a quantity of 0 or with five decimals, a unit price with three decimals or a currency symbol other than £, or 26 lines When the preview runs Then it is refused naming the field, and a description or reference starting with =, +, - or @ is made harmless as bank entries do

S17: Paid personally by a director (slice 3, issue #306) ​

Given type bill with paidBy: director and the director's own contact "Rob Duncan" When the preview runs Then the reference starts "Paid personally" and the card says the bill is settled against the company's Directors' Loan Account, naming the account (amended 2026-11-04, issue #335: QD-46 decided; S20) And with a contact that is not the named director the preview is refused

S18: Companies are isolated ​

Given a session with access to FEAW only When a preview names WealthTechPros, or a WealthTechPros preview ID is approved Then nothing is read or written

S19: Xero failures are plain ​

Given Xero answers 401, 429, a validation error or times out When the preview or Approve runs Then the reply says so in plain words (reconnect at /start for 401; the limit for 429; Xero's message for a validation error), and nothing is reported as created that was not

S20: A director-paid bill is settled against the Directors' Loan Account in the same card (slice 4, issue #335) ​

Given WEALTH TECH PROFESSIONALS LIMITED's chart has one active account 835 "Directors' Loan Account", a current liability with "Enable payments to this account" ticked When invoice_create_preview runs for the GBP 372.20 British Airways bill with paidBy: director, contact and directorName "Rob Duncan" Then the card says Approve creates the bill approved in Xero and pays £372.20 from 835 Directors' Loan Account, dated the bill's date When the owner presses Approve Then one PUT /Invoices creates the bill AUTHORISED, then one PUT /Payments pays its whole Xero total from that account by AccountID, each with an Idempotency-Key scoped to the preview ID And both are logged in ledger_write (invoice:<previewId>, invoice-payment:<previewId>), the outcome names the payment's Xero ID and the account, and the activity log keeps the account And with settleAccountCode the account the owner names is used, if it is an active liability account with payments enabled

S21: The Directors' Loan Account is never guessed (slice 4, issue #335) ​

Given a chart with no active liability account whose name contains "Director" and "Loan", or two of them, or a settleAccountCode that does not exist, is archived or is not a liability When the preview runs Then it is refused, naming the accounts found (or none), and says to give settleAccountCode or set the account up in Xero; nothing is stored and no account is created

S22: Payments must be enabled on the account (slice 4, issue #335) ​

Given the Directors' Loan Account does not have "Enable payments to this account" ticked in Xero When the preview runs, or the box is unticked between preview and Approve Then it is refused (at Approve, nothing is created) and says to tick "Enable payments to this account" on that account in Xero's chart of accounts and preview again

S23: A settlement that fails leaves the bill made (slice 4, issue #335) ​

Given an approved director-paid bill whose payment Xero refuses, or whose total Xero did not return When the owner presses Approve Then the bill stays made and approved in Xero, the outcome says it was not settled against the Directors' Loan Account and why, the failed payment is logged, and the card says partly written

Edge cases ​

  • Xero rounds VAT per line to the penny; a one-penny difference between the card's total and Xero's is possible. The outcome shows Xero's total.
  • A contact that is archived is not a match; the refusal says so.
  • Due date before the document date: refused.
  • A sales invoice for a company that is not VAT-registered (SPEC-020): only NONE is accepted once the profile says so.
  • The same receipt named on two documents in two cards: the second preview refuses the receipt (already linked) and keeps the document.

Dependencies ​

  • ADR 0043; ADR 0016 points 3 to 6; ADR 0022 point 1 and 2; ADR 0031 point 4.
  • SPEC-003 S38 (Approve writes), SPEC-005 (receipt guards), SPEC-010 (activity log), SPEC-011 S4 (write_status).
  • The accounting.invoices write scope and one reconnect per company.

Exit test ​

Rob creates the GBP 29.00 recharge invoice from FEAW to Wealth Tech Professionals Limited from Claude, approves it in the card, and Xero shows one draft invoice with that contact, the line, £24.17 net, £4.83 VAT and £29.00 total. Then, for WEALTH TECH PROFESSIONALS LIMITED, he creates the GBP 372.20 British Airways bill with the booking confirmation from the Xero inbox attached, and Xero shows one draft bill with the file on it.

Validation ​

idnameruleassert
V1Human approvalA document is created only by the card's ApproveS2, S3
V2Once per cardOne preview, one document; a repeat Approve writes nothingS2
V3Figures by codeNet, VAT and total are integer pence from the owner's quantity, unit price and the Xero rateS1, S15
V4Contact by IDExactly one active contact, by ContactID; no contact is createdS4, S5
V5Chart and locksCodes, rates, sides and lock dates are checked at preview and at ApproveS6, S7, S8
V6Evidence onlyA receipt is attached, never read into the documentS9, S10
V7Never authorisedDRAFT or SUBMITTED only, except a director-paid bill settled in the cardS13, S20
V8IsolationOne company's documents and files onlyS18
V9Settlement account by codeThe Directors' Loan Account is named by the owner or found once by name and class, with payments enabled; never guessed or createdS20, S21, S22