> For the complete documentation index, see [llms.txt](https://help.tahua.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tahua.io/product-news/2026/june/xero-bank-account-sync.md).

# Sync applicant bank account details to Xero contact on milestone bill sync

When a milestone bill is synced to Xero, the applicant's bank account number is automatically written to the corresponding Xero contact's bank account field. This enables Xero's batch payment file generation to include correct bank details without manual data entry, eliminating the risk of payment errors from miskeyed bank details.

The bank account is re-synced on every bill sync, so if an applicant updates their bank details, the Xero contact is always up to date.

Note: Xero allows only one bank account per contact. If two applications for the same entity are processed in the same batch, the bank account used will be whichever was synced last.

## Enabling the feature

This feature is off by default. To enable it, go to **Admin > Settings > Xero Integration** and tick the "Sync bank account to Xero contact" checkbox. When disabled, milestone bill syncs will not update the Xero contact's bank account field.

## Bank account lookup sequence

When syncing, the system looks for a bank account number by checking the following places in order, using the first non-blank value it finds:

1. **Milestone template** — If the milestone has a bank account field on its template, that value is used first. This allows the bank account to be captured or overridden on a per-milestone basis.
2. **Contract** — The bank account number stored on the contract.
3. **Application** — The bank account from the application form (or, for contract-only milestones, the application linked to the contract).
4. **Registration** — The bank account from the applicant's registration form.

This means a bank account set closer to the milestone (e.g. on the milestone template or contract) will always take priority over the one on the application or registration.

## Known limitations and risks

**Old milestone re-sync overwrites newer bank account** — If an entity has two applications with different bank accounts (e.g. Bank A in 2024, Bank B in 2025), and an admin manually re-syncs a 2024 milestone (e.g. to correct an amount), it will overwrite Bank B with Bank A on the Xero contact. The next bill sync from the 2025 application will restore Bank B, but there is a window of risk. G has indicated they don't expect two concurrent applications from the same entity.

**Contract milestones with no linked application** — If a milestone belongs to a standalone contract that is not linked to a funding application, `funding_application_or_contract_funding_application` returns nil and no bank account is synced. The Xero contact's bank account field will be left as-is (empty if never set). This is silent — no error is raised.

**Xeroizer `Contact.build` save behaviour** — When an existing contact is located via its stored Xero contact ID, the sync builds a minimal contact object (ID only) and saves it with just the bank account field set. This relies on Xeroizer serialising only explicitly-set fields in the POST body. If it instead serialises all fields including nil values, it could blank out the contact's name, email, and address in Xero. This has not been verified against the gem's behaviour.
