> This is the Markdown of a Backed Help Centre page, https://admin.backed.giving/help/integrations/xero.md. Every page is listed at https://admin.backed.giving/help/llms.txt.

> This page uses Backed's default terms, such as Funding Round and Application Template. An organisation may rename them, so read each as your organisation's own term if you've renamed it.

When your organisation is connected to Xero, each milestone creates a bill in Xero at the sync point
you choose. The `Xero` section sits at the foot of `Settings > Profile and terms`, under Slack and
Microsoft Teams. You need the `Can manage Integrations` permission to connect, test, disconnect or
change its options. Anyone who can open the page sees whether Xero is connected.

Your organisation can connect one accounting system at a time. While QuickBooks Online or MYOB is
connected, `Connect to Xero` is unavailable and says which one to disconnect first.

## Connect to Xero

1. Go to `Settings > Profile and terms`.
2. In the `Xero` section, select `Connect to Xero`.
3. Sign in to Xero if it asks, and allow Backed to reach your organisation.
4. If your Xero login reaches more than one organisation, choose the one to connect.

You come back to `Settings > Profile and terms`, where the section reads "Connected to" and your
Xero organisation's name. If you cancel on Xero's screen, or the connection fails, nothing is stored
and the page says "The connection to Xero was not completed. Please try again."

The first time you connect, `When the Milestone is approved` is ticked as the sync point.

## Test or disconnect the connection

- `Test connection` asks Xero who you are connected to. It names the organisation when the
  connection works, and shows what Xero said when it doesn't.
- `Disconnect` asks you to confirm: "Disconnect Xero? Milestones will stop syncing and payment
  information will no longer be pulled." Choose `Cancel` to stay connected. Bills already in Xero
  are left as they are, and your options are kept for when you reconnect.

If Xero stops accepting the connection, the section says "The connection to Xero was lost.
Reconnect to resume syncing." Select `Connect to Xero` again to resume.

## Choose the options

Select `Edit Details` at the top of the page, then change the options in the `Xero` section and
select `Save Xero options`. The section's options save on their own: the page's `Save` doesn't
include them.

| Option | What it does |
| --- | --- |
| `Xero Account Code` | The account every bill is coded to, unless a grant's set-up names its own Xero account code. Shown as "code – name". |
| `Tracking Category` | "We will create an option for each funding category under this tracking category." Leave it as `None` to send bills without tracking. |
| `Milestone sync points` | When a milestone's bill is created or updated: `When the Milestone is approved`, `When the Contract is executed`, or both. With neither ticked, no bill is created. |
| `Sync error email address` | Where Xero sync errors are emailed. Leave it blank to send no sync error email. |

There is no GST setting in the Xero integration. GST on each bill follows the applicant's GST Field.

If someone else saved the options since you opened the page, saving tells you so: select `Reload`
to see their changes, then make yours again. An address that isn't a valid email shows "Enter a
valid email address".

## The grant's own account code

While Xero is connected, a grant's set-up offers its own Xero account code. Bills for that grant
use it instead of the `Xero Account Code`. The field is hidden while Xero isn't connected.

## An applicant's Xero Contact and Bank Account Sync

While Xero is connected, an applicant's page shows a `Xero` section on its `Details` tab. It is
hidden while no accounting system is connected, and under QuickBooks Online or MYOB, which match
the vendor or supplier by name only.

- `Xero Contact` names the contact the applicant's bills go to, and whether it was matched by name
  or chosen here. Before the first bill it says none is chosen yet.
- To choose a different contact, select the pencil, type part of its name and pick it from the list
  of up to 20 active Xero contacts. Select `Use this contact` to save it, or press `Escape` or
  `Cancel` to leave it as it was. The next bill uses the contact you chose and no new contact is
  created. Bills already in Xero are not changed.
- `Bank Account Sync`, when on, writes the bank account on file to the Xero Contact before each
  application or contact payment's bill. The account number is never shown in Backed's logs or
  history; the history records only that the switch was turned on or off.

You need the `Can access Users` permission to change either; anyone who can open the applicant
sees them.

## Frequently asked questions

Each answer is what Backed does today; the last column names the spec that proves it.

| Question | Answer | Proved by |
| --- | --- | --- |
| Which Xero organisation do bills go to? | The one you chose when you connected. Your organisation connects one Xero organisation at a time. If you disconnect and connect a different one, new bills go there and the bills in the first are left as they are. | ACC-4 `xero-mapping.spec.ts` ("lists the organisations this consent reached"); ACC-6 `bill-sync.e2e-spec.ts` ("ledger A, disconnect, ledger B") |
| Is there a GST setting? | No. GST on each bill follows the applicant's GST Field, coded with the tax rates your Xero organisation holds: `INPUT` or `BASEXCLUDED` in Australia, `INPUT2` or `NONE` in New Zealand. | ACC-4 `xero-mapping.spec.ts` ("the tax types, read from /TaxRates"); ACC-6 `bill-sync.e2e-spec.ts` ("billed after carries GST") |
| Which Xero contact does a bill name? | The `Xero Contact` chosen on the applicant's page, if there is one. Otherwise the contact whose name matches the applicant's exactly, ignoring case and spacing. If none matches, Backed creates one; if more than one matches, the sync fails with "More than one matching contact". | ACC-6 `counterparties.spec.ts`; ACC-10 `counterparty.e2e-spec.ts` ("the next Bill uses it with no new Contact") |
| Are the applicant's bank details sent to Xero? | Only while the applicant's `Bank Account Sync` is on: the bank account on file is written to the Xero contact before each application or contact payment's bill. With it off, no bank details are sent. | ACC-9 `bank-account-sync.spec.ts` ("reads nothing with the switch off"); ACC-10 `counterparty.service.spec.ts` |
| Are files attached to the bill? | Yes. Each milestone bill carries the milestone's audit document and its files marked `Is an invoice`. A file Xero refuses leaves the bill synced, and the refusal is recorded. | ACC-15 `bill-sync-documents.e2e-spec.ts` ("attaches the audit document and ONLY the Is an invoice files") |
| How does the tracking category work? | Backed adds an option for each funding category under the `Tracking Category` you chose, the first time a bill needs it, and reuses it after. Renaming a funding category adds a new option; the old one stays. | ACC-15 `tracking-options.spec.ts` |
| What happens if the bill date is inside Xero's lock date? | The bill is not created. The milestone shows `Sync failed` with Xero's words naming the date, and the `Sync error email address` is emailed. Move the lock date in Xero, then retry the sync. | ACC-4 `xero-errors.spec.ts` ("a Bill dated inside the lock date"); ACC-7 `sync-failure.handler.spec.ts` |
| Does Backed change a bill once it is approved, paid or voided in Xero? | No. Backed updates only a bill that is still a draft. Any other bill is left as it is, and the milestone shows why. | ACC-4 `xero-errors.spec.ts` ("an update Xero has moved on is refused before it is sent") |
| How do payments made in Xero reach Backed? | Each night Backed reads the payments recorded against its bills and records them on the milestone. | ACC-11 `payment-pull.service.spec.ts` |
| Where can I see each sync attempt? | On `Settings > Profile and terms > Integration logs`. Choose `Xero` under `Integration` to see only Xero's entries, and select `Show details` on an entry for its attempt, bill number, milestone and error. See [Integration logs](integration-logs.md). | ACC-14 `integration-log.store.spec.ts` |