Xero

This page covers everything specific to Xero: connecting, every setting on the connection page, how your documents look inside Xero, and the Xero rules the integration handles for you. For how the accounting export works in general (what triggers an export, account mapping, closed periods, history import), start with the accounting overview.

Before you connect

Xero shows as available on request while Xero's review of our app completes. Use the Request access button on the integration card and we will enable it for your account.

You need a Xero organisation and a login that can approve app connections for it. If you want to try the integration without touching real books, every Xero login includes a free Demo Company you can connect instead; it resets itself every 28 days.

Connecting

1. Go to Settings, then Integrations, and select Connect on the Xero card.
2. Sign in to Xero. Xero asks which organisation to connect; each connection binds to exactly one.
3. You land back on the connection page, connected. The connection is named after your Xero organisation; rename it any time with the pencil next to the name.

Need a second organisation? Use Add another connection on the same card. Each connection gets its own page and its own settings. Add another connection always makes a new one: if a connection is disconnected or has an error and you want that same organisation back, open its page and use Reconnect instead, which keeps its account mapping and routing.

On Xero's approval screen you will see exactly what access is requested: invoices and credit notes, payments, contacts, and your organisation settings. The settings access is what lets the mapping pickers list your chart of accounts and tax rates.

You can connect several organisations at once. Two organisations for two legal entities is a supported setup; each connection keeps its own account mapping, routing and settings. See billing entities for how documents are split between them.

If a connection stops working, the page shows Reconnect. Reconnecting refreshes access and keeps your settings and mappings.

Finishing setup

A newly connected Xero connection cannot export anything yet, so the page opens as a two step checklist:

1. Choose which billing entities export here. A document belongs to one billing entity and must reach one set of books. If you run a single entity, tick it and move on.
2. Map the required accounts. Revenue and Payments received have no sensible default; money lands where you choose, nowhere else.

The full configuration page appears once both steps are done.

Where each amount lands

The account mapping grid pairs each part of an invoice with something in your Xero organisation. The pickers list what is actually in your organisation, read when you connect. If an account you just created in Xero is missing from a picker, use Reconnect on the connection page to re-read your chart of accounts; your settings and mappings are kept.

• Revenue (required): the account your invoice lines post under. Only active accounts are offered.
• Payments received (required): the bank or clearing account payments post to. Xero only accepts payments into an account with Enable payments to this account switched on, so the picker tells you which of your accounts qualify. If the account you want is missing, open it in Xero and enable payments on it, then reconnect to re-read your accounts.
• Tax rate: which of your Xero tax rates an exported line files under. Only active rates that can apply to revenue are offered. Leave it blank and each line uses its account's default rate; the amounts still cross exactly either way.
• Discounts: discounts post as their own negative line against this account, so they never net against revenue and understate it.
• Prepaid credit: where a customer spending balance they already paid for draws from. See wallets for how prepaid balance works.
• Credit notes: where credits you issue are recognised. A credit note posts as a Xero credit note. See credit notes.
• Everything else: the catch-all item for anything not mapped above, so a partly configured connection exports rather than failing.

Under Overrides you can point one product at a different account, or route payments from one gateway or one currency to their own deposit account, so a Stripe payout and a bank transfer reconcile separately. The most specific route wins.

How your documents appear in Xero

• An invoice you finalise becomes an approved (authorised) Xero invoice, ready in your sales ledger rather than sitting as a draft; a payment is applied against it; a credit note arrives as an approved credit note. See the invoice lifecycle for when each of those happens.
• Line amounts arrive exactly as invoiced. Where a unit price times quantity would not reproduce the line total exactly, the integration sends the line total alone, because Xero recomputes lines from unit prices and would silently change what the line is worth.
• Unit prices are sent with four decimal places. Usage based billing routinely prices below a cent, and at Xero's default of two decimal places those unit prices would round and the recomputed line would drift.
• Each exported contact carries your customer's yRecurring ID in Xero's contact number field, which Xero describes as the field for identifying contacts from external systems. An accountant can trace any record back to its source.
• Xero's field limits are handled for you: long names, references and descriptions are shortened to fit rather than failing the document.

Currencies

A Xero organisation can hold documents in any currency your subscription supports; there is no switch to flip. Each document exports in its own currency, and drift checks convert totals using each document's currency, so organisations mixing currencies reconcile correctly.

A customer has one currency, in both systems. A customer billed in two currencies is not something either side can represent.

Tax

Xero takes tax line by line. Each line carries its exact tax amount as invoiced, overriding what Xero would have computed, so two rounding methods can never disagree by a penny. If you mapped a Tax rate, the line files under that rate; otherwise it files under the account's default rate, with your exact amount still standing. See how tax is applied for where the figures come from.

Importing your history

Import history on the connection page brings your existing ledger into Xero: issued invoices, then the payments that settled them, then credit notes, in that order, so every invoice is credited with its payment.

Xero allows 5,000 API calls per day per organisation, so a large history is honestly a multi day job: roughly 1,600 documents per day. The import paces itself to stay inside the allowance, shows progress in Activity as a single summary row, and picks up where it left off the next day rather than racing to the limit and failing for the rest of the day. Anything skipped or failed sits behind a drill-in with its reason.

If a connection is deleted and set up again

Xero requires invoice numbers and contact names to be unique, so re-sending something it already holds fails outright rather than duplicating it. To keep that from becoming a dead end, the export looks first: an invoice is matched on its number, and a contact on the contact number we write into every record we create, which is the field Xero provides for identifying contacts from other systems. A match is updated instead of re-created.

If the number belongs to an invoice for a different amount, the export stops and names it rather than overwriting it.

Keeping your books honest

The integration re-checks documents it has already sent and reports drift: a record whose total was edited in Xero, or one that was voided or deleted there. Xero removes voided and deleted invoices from your ledger, and the integration reports them as gone rather than as totals that drifted to zero. It reports only. It never rewrites something your bookkeeper changed on purpose.

Limits and quirks, in one place

• Xero's API allows 5,000 calls per organisation per day, which is what makes a large history import a multi day job.
• The payments account must have Enable payments to this account switched on in Xero, or Xero rejects the payment.
• Only active accounts, and only active revenue-applicable tax rates, are offered in the pickers.
• Long names and references are shortened to Xero's field limits automatically.
• Voiding and refunding do not sync yet, in either direction. A refund you issue here needs a matching entry in Xero by hand. See refunds.
• Credit notes carry no tax. Every line states a tax amount of zero, so Xero adds none of its own from the account default rate and the tax on the original invoice is not reversed. Credit a tax-charged invoice for its full total including tax, or it will keep showing the tax portion as owed, and adjust the tax in Xero by hand.