Where Xero touches BMS
Xero is not confined to its own screens. Behaviour changes in several modules depending on whether an accounting integration is switched on and connected. This is the catalogue of those places, so that behaviour which looks like a quirk can be recognised as the integration doing its job.
The switch
Two conditions have to hold before any of it happens.
| Condition | Where |
|---|---|
The accounting integration is set to xero |
A system setting. Valid values are bms, xero and quickbooks; anything else reads as none |
| The organisation is configured | The organisation has a Xero tenant, and is not a staging instance |
Important
Staging instances are deliberately excluded. A copy of the production database running as staging will not push to the real Xero organisation, even though it holds the same tokens. This is why a staging environment can look connected and never sync — that is correct, not broken.
Invoices
| Behaviour | What the integration does |
|---|---|
| Completing an invoice | When Xero is the accounting integration and the organisation is configured, an invoice cannot be completed in BMS. Completion is Xero's to report, not yours to set |
| The Completed date | Taken from the invoice's Xero cross-reference — specifically, the last time Xero was read. An invoice with no cross-reference shows -- |
| Direct debit toggling | Which invoice states allow direct debit to be switched depends on the accounting integration, and on whether the payment gateway is BMS's own |
| Bulk processing | Pushes the customers first, then the invoices, grouped by entity. A push that fails is rescheduled rather than lost |
| Manual sync | Invoices can be pushed on demand rather than waiting for the background run |
That first row explains the most common piece of confusion in Billing: the Complete action is unavailable and nothing says why. Xero is holding it. The invoice completes when payment comes back from the books.
Purchase invoices
Purchase invoices from Stock — including those generated by agent reconciliations — are pushed grouped by entity, as accounts payable.
Payments
Payment methods resolve the customer's Xero contact when setting up and taking payment, so a customer that has never synced cannot be matched.
Period locking
A domain's period lock date is taken from Xero. BMS reads the lock date from each connected organisation and adopts the most restrictive one.
Closing a period in Xero therefore closes it in BMS, without anyone changing a setting here. If BMS starts refusing to post into a month, this is the first thing to check.
Tracking categories
Xero's tracking categories are pulled in and held against the entity. Records created in other modules stamp themselves with the entity's categories — a service job sets its tracking categories on save — so that BMS documents carry the dimensions Xero reports on.
Cross-references
Xero cross-references hang off records in several modules: invoices, invoice lines and line items, customers, suppliers, tax rates, ledger accounts, and stock purchase invoice lines. Each records what kind of Xero object it maps to and when it was last pulled, and provides the deep link into Xero.
An entity's link to its accounting organisation is the same idea at the top: an entity belongs to a Xero organisation.
Admin screens
| Screen | Xero behaviour |
|---|---|
| Admin → Entities (Organisations) | Connect, show authentication state, remove authentication |
| Admin → Accounts | Compare the chart of accounts against Xero, import from it |
| Admin → Tax Rates | Compare and import tax rates |
Ignore the second Xero surface
A second set of Xero screens exists at /integration/xero, with its own
organisations, settings, account and tax-rate imports and a product export.
Warning
These screens are not used. The live integration is the one described on
this page, administered from /admin. The Integration screens read the same
organisation records through a different code path, and the authorisation state
they display is stale — they show refresh tokens that expired years ago while
the Admin screen correctly reports the organisations as authenticated.
Do not use them to judge whether Xero is connected, and do not connect or disconnect from them. Admin → Entities is the authority.