Outstanding Invoice & Bill Import with Clearing Mode

Outstanding Document Import

You can now import outstanding (unpaid) invoices and bills from your previous accounting system. This completes Phase 3 of the Universal Data Import pipeline — the last piece needed for a full self-service migration.

Invoice Import

• CSV upload at /invoices/import — drag-and-drop your outstanding invoices CSV with columns for contact name, invoice number, date, due date, total, and amount paid.
• Contact resolution — every contact in your CSV is matched against existing contacts using fuzzy matching (Levenshtein similarity ≥ 85%). Unmatched contacts are auto-created on confirm.
• Partial payment detection — invoices with amounts already paid are handled correctly. The gross amount flows through clearing; a synthetic payment records the paid portion.
• Clearing proof — before you can confirm, the system verifies that your imported invoices account for the full Trade Debtors balance from your opening balances. No double-counting, no orphaned balances.

Bill Import

• CSV upload at /bills/import — mirror of the invoice importer for supplier bills, with the same contact resolution and clearing proof against Trade Creditors.

Opening Balance Clearing Mode

• New option on OB upload — when importing opening balances, you can now enable Clearing Mode. This posts Trade Debtors to a Migration Clearing account (1198) and Trade Creditors to another (2198) instead of the control accounts directly.
• Why it matters — clearing mode enables the zero-sum invariant. When you subsequently import outstanding invoices totalling your Trade Debtors balance, the clearing account nets to zero — mathematical proof that nothing was lost or double-counted during migration.
• Backwards compatible — existing opening balances continue to work in Direct Mode. To use the invoice/bill importers, void and re-import with Clearing Mode enabled.

Cash VAT Protection

• Structured error for Cash VAT — if your organisation uses Cash VAT accounting, invoice and bill import is blocked with a clear error message. Accrual-basis outstanding documents and cash-basis VAT recognition don’t mix safely. This will be supported in a future release.

Account Mapping Improvements

• 17 new dictionary mappings — the opening balance mapper now correctly resolves common account names from Xero, FreeAgent, and QuickBooks exports. Previously unmapped accounts like Wages & Salaries, Advertising, Corporation Tax, Office Equipment, Telephone & Internet, and Suspense now map automatically to the correct SpeyBooks chart accounts.

Technical Details

• Atomic commits — invoice and bill confirms run inside a single database transaction. Contacts, invoices, invoice lines, clearing journals, and synthetic payments are all created or none are.
• 5 new API endpoints per direction — upload, retrieve, confirm, void, and delete for both /invoice-imports and /bill-imports.
• Direction-agnostic engine — the underlying closure engine doesn’t know whether it’s processing invoices or bills. Routes inject the direction; the engine enforces the invariants.