Xero integration: how-to

Step-by-step instructions for the Xero integration, in the order you’ll usually need them. For what each option means, see Xero integration; for problems, see Xero integration: troubleshooting.

Find your task

If you’re here because…	Go to
You’re connecting Xero for the first time	Connect COHO to Xero, then Set up your mappings
Your contacts already exist in Xero	Link existing Xero contacts
You want to check the setup before sending everything	Test with one tenancy or supplier
You want to send rent, supplier bills or settlements now	Run a sync by hand
You want Xero kept up to date without thinking about it	Turn on automatic sync
A sync shows errors, or an Action says automatic sync is blocked	Read and clear sync errors
You’ve changed accounts or tracking in Xero	Re-send items after changing mappings
Something in Xero is wrong for one tenancy, supplier or settlement	Remove and re-send one item’s data
You use more than one company or Xero organisation	Add another integration
The page says “Your connection has expired”	Reconnect Xero
You want to stop syncing	Disconnect Xero, or archive an integration
Your bank also feeds into Xero	Reconcile rent in Xero alongside COHO

Connect COHO to Xero

Do this when you’re setting up the integration for the first time.

Before you start: you need Integrations (edit) permission in COHO, and a Xero login that can connect apps to the Xero organisation. Make sure your properties have ownership details, and use Rent Collection; properties without Rent Collection aren’t included.

1. From your dashboard, click Menu > Finances, and open Connections & Synchronisations.
2. Click Add Xero account.
3. Choose what this integration covers: All properties, Properties owned by (then pick the Property owner), or Properties tagged with (then pick the Tag string).
4. For each of Synchronise Rent Books, Synchronise Supplier Settlements and Synchronise Property Owner Settlements, choose Yes or No. For each Yes, set the Staging date (Sync items from). Nothing dated before it is sent to Xero, so pick the date your Xero records should start from in COHO.
5. For rent books, choose Create rent invoices days ahead (Default (7 days or if paid) suits most people).
6. Leave Automatic Xero sync on No for now. Click Create.
7. In the new row, click the Xero connect button and sign in to Xero. Allow access and choose your Xero organisation.
8. If you can access several Xero organisations, COHO asks you to “Choose the Xero tenant you want to link”. Pick it under XERO Tenant / Account and click Save as Xero tenant for this integration.

What happens next: the page says “Yeehaw - Success”, and the integration shows your Xero organisation and when the connection expires. View now appears on the row.

Caution

You can’t change which Xero organisation an integration is linked to later. Check you’ve picked the right one. To use a different organisation, archive this integration and add a new one.

Set up your mappings

Do this after connecting, and before your first sync.

Before you start: you need Finances (edit) permission. Ask your accountant or bookkeeper which Xero accounts to use.

1. On Connections & Synchronisations, click View on the integration.
2. Under Synchronisations, click Pull accounts, categories, and contacts. COHO lists what it brought in, for example “42 XERO chart of accounts updated or added”.
3. Open Chart of Accounts. For each section you use, choose an account in the columns that apply to you (Owned, Rent-to-Rent, Managed):
   • Settlements & supplier expenses: each financial item category. For costs your organisation pays and then recovers from the owner, fill in the Owned properties & disbursements column, even for managed properties.
   • Rent charges: rent, deposits, holding deposits and other charges.
   • Rent payment sources: each way tenants pay. Use a bank account or an account that accepts payments.
   • Bank accounts: each bank account connected to COHO, to its Xero bank account.
4. Open Tax Rates. For each rate you use, choose the Expense tax in Xero and Income tax in Xero.
5. Open Tracking Categories if you report by property or owner in Xero, and choose up to two options for each property, owner or room. Click Add option to create a new option in Xero.
6. Open Contacts and link any that already exist in Xero (see the next task).

What happens next: each choice saves straight away. Rows you don’t use can stay blank; a sync only complains about a missing mapping when it needs it.

Tip

Some Rent charges mappings may already be filled in. COHO suggests them when your Xero uses standard account codes. Check them; COHO never overwrites a mapping you’ve chosen.

Link existing Xero contacts

Do this before your first sync if your tenants, suppliers or owners are already in Xero, so COHO doesn’t create duplicates.

1. On the Xero page, open Contacts.
2. Link This organisation to your own contact in Xero.
3. Open Suppliers and Property Owners, and pick each one’s Xero contact.
4. Open each property and pick each tenancy’s Xero contact.
5. To save time on tenancies, go to Synchronisations and click Match tenancy contacts. COHO links each tenancy to a Xero contact whose account number is the tenancy number, or whose name contains it in brackets, for example “(TE1009)”.

What happens next: anything still unlinked gets a new Xero contact on its first sync. For suppliers and owners, COHO first looks for a Xero contact with the same email.

Test with one tenancy or supplier

Do this before you send your whole portfolio.

1. On the Xero page, under Synchronisations, click Test. You should see “Finished testing the connection successfully”.
2. Open Synchronise Tenant Rents and choose Specific Tenancy. Pick one tenancy.
3. Tick Only produce report and click Synchronise selected tenancy. Read the log: it lists what would be created.
4. Fix anything in Errors, then run it again without Only produce report.
5. Check the invoices and payments in Xero.
6. Do the same for one supplier (A specific supplier) and one settlement (A specific settlement) if you use those.

What happens next: when the test looks right, sync everything (see the next task).

Run a sync by hand

Do this to send changes to Xero now, or for your first full sync.

Before you start: the integration must be connected, with that sync type set to Yes.

1. On the Xero page, open Synchronise Tenant Rents, Synchronise Supplier Invoices & Commissions or Synchronise Property Owner & Organisation Settlements.
2. Choose what to sync: one item, one property or owner, or everything in this connection.
3. Leave Incremental - Only changes since… ticked for a quick sync. Untick it for a full check.
4. If the last sync of this type had errors, tick “The last tenancy sync completed with errors. Confirm you have reviewed those errors and want to proceed.” (or the supplier or settlement version).
5. Click the synchronise button, for example Synchronise tenancies in 47 properties. Confirm if asked.

What happens next: the sync appears in the table as Queued, then Running. Large portfolios can take a while; you can leave the page. When it shows Completed, check the Errors count.

Note

Only one sync runs at a time per integration. Wait for the current one to finish, or click Stop.

Turn on automatic sync

Do this once a full sync runs cleanly.

1. On Connections & Synchronisations, click Edit on the integration.
2. Open Automatic Xero sync and choose Yes.
3. Choose the Frequency: Daily or Weekly (Mondays).
4. Turn on Sync tenancies, Sync property owner settlements and Sync supplier items as needed. You must choose at least one.
5. Check the pause setting: by default, “Automatic syncs will not run if the latest connection-wide sync of the same type has errors”. Click Change to switch it.
6. Optionally, click Change next to the actions setting and choose who gets this integration’s Actions.
7. Click Update.

What happens next: COHO syncs early each morning (between midnight and 9am UK time), on Mondays only if weekly. Automatic syncs show “(Automatic)” in the sessions table, and the badge by Synchronisations shows the schedule.

Read and clear sync errors

Do this when a sync shows errors, or you get an Action such as “Resolve Xero tenancy synchronisation errors”.

1. On the Xero page, find the sync in the table and click Errors. Each error says what failed and usually what to do.
2. Fix the cause. Most are a missing mapping, a property with no ownership details, a payment not fully matched to charges, or something changed in Xero. See Xero integration: troubleshooting.
3. Run the same sync again. For an Action, run a full sync of that type for the whole connection.

What happens next: when a full sync of that type finishes with no errors, the Action closes and automatic sync of that type starts again.

Tip

An error you can’t fix, such as a partly kept deposit, will block automatic sync every time. You can set Pause automatic syncs when the latest connection-wide sync has errors to No under Edit; the error still shows on each sync.

Re-send items after changing mappings

Do this after you change accounts, tax rates or tracking options, so items already in Xero pick up the change.

1. Run a sync (see Run a sync by hand).
2. Tick Force update (very slow) and untick Incremental.

What happens next: COHO re-sends every item in range, even if it hasn’t changed. Items dated before your Xero lock date can’t be changed; COHO skips them with a warning, or an error if the amount has changed.

Remove and re-send one item’s data

Do this when one tenancy’s, supplier’s or settlement’s data in Xero is wrong and you want COHO to start again for it.

1. On the Xero page, open the sync for that type and choose Specific Tenancy, A specific supplier, or A specific settlement (or A specific property owner).
2. Click Remove tenancy data from Xero (or Remove supplier data form Xero, Remove settlement data from Xero, Remove settlements data from Xero for property owner). Confirm.
3. Run a normal sync for the same item.

What happens next: COHO deletes or voids the invoices, payments and other data it created on that Xero contact; the contact stays. The next sync creates them again from COHO.

Caution

COHO can’t remove a bill that has payments added in Xero. Remove or unreconcile those payments in Xero first.

Add another integration

Do this when different properties belong in different Xero organisations, for example one per company.

1. On Connections & Synchronisations, click Add Xero account.
2. Choose Properties owned by or Properties tagged with, and pick the owner or tag.
3. Set up and connect it as in Connect COHO to Xero.

What happens next: those properties move to the new integration. An All properties integration covers whatever’s left.

Caution

A property mustn’t match two integrations. If it’s both owned by an owner with an integration and tagged with a tag that has one, it isn’t synced and the sync reports an error.

Reconnect Xero

Do this when you see “Your connection has expired” or Expired, or a sync says to reconnect.

1. On the Xero page, click Reconnect (or Reconnect on the integration’s row).
2. Sign in to Xero and allow access to the same Xero organisation.

What happens next: the connection shows a new expiry date. Your settings, mappings and sync history are kept. Run a sync to catch up.

Disconnect Xero, or archive an integration

Do this when you stop using Xero, or no longer need an integration.

1. On Connections & Synchronisations, find the integration.
2. To stop COHO talking to Xero, click Disconnect, then Disconnect to confirm. To put the integration away as well, click Archive.

What happens next:

• Disconnect: COHO can no longer reach Xero, so syncs (including automatic ones) stop. Everything already in Xero stays. Your settings and mappings are kept, so you can reconnect to the same Xero organisation later.
• Archive: turns off every sync on the integration and hides it (turn on Archived only to see it). Restore brings it back, but you’ll need to switch its syncs on again under Edit.

Reconcile rent in Xero alongside COHO

Do this if your bank account also feeds into Xero.

1. Match rent in COHO as usual (see Transactions), then sync tenancies.
2. In Xero, match each rent bank line to the payment COHO created. Don’t create a new payment or “receive money” for it, and don’t reconcile it straight to the invoice.
3. Check your Xero bank rules don’t create payments for rent automatically.

What happens next: each rent payment appears once in Xero. If a payment added in Xero would overpay a COHO invoice, the next sync removes it so it can add its own.

Note

How you treat these lines in Xero is an accounting choice. Check with your accountant or bookkeeper.