Xero integration · Product guide
Xero integration
The Xero integration sends your COHO records into Xero, so your accounts stay up to date without typing everything twice. COHO is the source of truth: you record rent, payments, supplier costs and settlements in COHO, and COHO creates the matching invoices, bills and payments in Xero.
It works one way. Changes you make in Xero don’t come back to COHO, except whether supplier bills and settlement bills have been paid.
For step-by-step instructions, see Xero integration: how-to. For problems and error messages, see Xero integration: troubleshooting.
Why you’d come here
Section titled “Why you’d come here”| You want to… | Usually you start from | Go to |
|---|---|---|
| Connect COHO to Xero for the first time | Menu > Finances > Connections & Synchronisations > Add Xero account | Connect COHO to Xero |
| Tell COHO where things go in Xero: accounts, VAT, tracking, contacts | The Xero page’s Chart of Accounts, Tax Rates, Tracking Categories and Contacts | Mappings |
| Send rent, supplier bills or settlements to Xero | The Xero page’s Synchronisations | Run a sync |
| Make it automatic | Edit on the integration > Automatic Xero sync | Turn on automatic sync |
| Fix sync errors, or an Action says automatic sync is blocked | The sync’s Errors link | Xero integration: troubleshooting |
| Reconnect after “Your connection has expired” | The Xero page, or Reconnect on the integration | Reconnect Xero |
| Stop using Xero, or swap to another Xero organisation | Disconnect or Archive on the integration | Disconnect or archive |
Which screen to use:
| Screen | Use it when you’re thinking about |
|---|---|
| Connections & Synchronisations (in the Finances panel) | Your Xero connections: adding one, connecting, settings, disconnecting |
| The Xero page (View on a connection) | Day-to-day work: running syncs, reading errors, mappings |
| Financial Settings > Xero Management (Manual Exports) | Only the CSV export (Export Accounting Data). It’s separate from the integration; see Finances & reports |
How it works
Section titled “How it works”- Connect. You add a Xero integration in COHO, sign in to Xero and choose the Xero organisation to link.
- Choose what it covers. An integration covers All properties, the properties of one owner, or the properties with one tag. You can have several integrations, for example one per company, each linked to a different Xero organisation.
- Choose what to send, and from when. Rent books, supplier bills and owner settlements are each switched on separately, with a Staging date (Sync items from). Nothing dated before it is sent.
- Map. You pull your Xero accounts, tax rates, tracking categories and contacts into COHO, then tell COHO which to use.
- Sync. A sync compares COHO with what it sent last time and creates, updates or removes items in Xero. You run syncs by hand or on a daily or weekly schedule.
What goes to Xero:
| In COHO | In Xero | Sent when you sync |
|---|---|---|
| A tenancy | A customer contact named after the tenants, property, room and tenancy number | Tenancies |
| Each rent charge (rent, deposit, holding deposit, rent in advance, other charges) | One invoice per charge, approved, dated on the charge’s due date | Tenancies |
| A rent payment matched to charges | A payment against those invoices, paid into the account you mapped | Tenancies |
| A refund of a charge | A bill to pay on the tenant’s contact | Tenancies |
| A financial item with a specific supplier | A bill to pay on the supplier’s contact (or a credit note for a refund), with the invoice file attached | Supplier items |
| An owner settlement | Bills between the owner, your organisation and the client money account, with the statement attached | Property owner settlements |
What comes back from Xero:
- Paid status for supplier bills and settlement bills. See Rules and automatic behaviour.
- Your accounts, tax rates, tracking categories and contacts, when you click Pull accounts, categories, and contacts.
Where to find it
Section titled “Where to find it”| Where | Shows |
|---|---|
| Menu > Finances > Connections & Synchronisations | Your Xero integrations, with Add Xero account, Edit, View, Archive |
| View on an integration | The Xero page for that connection. Its menu has Synchronisations; under Xero Mappings, Chart of Accounts, Tax Rates, Tracking Categories and Contacts; and under Settings, Configuration |
View only appears once the integration has been connected to Xero.
What you see
Section titled “What you see”Connections & Synchronisations
Section titled “Connections & Synchronisations”A table of your integrations. Turn on Archived only to see archived ones.
| On screen | What it shows or does |
|---|---|
| Properties | What it applies to: “Owned by [owner]”, “Tagged with [tag]”, or “(All remaining properties)” |
| Account | The linked Xero organisation, and when the connection expires (“Expires in…”) or Expired |
| Tenancies, Suppliers, Settlements | Which syncs are on, with their from and to dates |
| Xero connect button | Signs in to Xero and links an organisation. Shown until the integration is connected |
| Choose Xero tenant | Shown if you have access to several Xero organisations and haven’t picked one |
| Reconnect | Signs in to Xero again when the connection has expired |
| Disconnect | Disconnects from Xero (asks “Are you sure you want to disconnect this Xero account?”) |
| View | Opens the Xero page |
| Edit | Opens the integration’s settings |
| Archive / Restore | Puts the integration away, or brings it back |
| Add Xero account | Adds a new integration |
The Xero page
Section titled “The Xero page”The heading is the Xero organisation’s name, followed by “This connection contains [n] properties”, with how many are excluded because another integration covers them. With several integrations, Switch to… or Switch moves between them.
COHO also shows:
- a tip when properties or owners have no tracking option, for example “Add tracking options for 3 properties”;
- “Your connection has expired. Reconnect your Xero account to continue.” when the connection needs renewing.
Synchronisations
Section titled “Synchronisations”| On screen | What it does |
|---|---|
| Badge beside Synchronisations | The automatic sync state: for example Daily auto sync, Auto sync blocked, Auto sync partially blocked or Auto sync failed |
| Pull accounts, categories, and contacts | Brings in your Xero accounts, tax rates, tracking categories and contacts, and fills in some suggested mappings |
| Match tenancy contacts | Links tenancies to Xero contacts that already contain the tenancy number |
| Test | Checks COHO can talk to Xero, without changing anything |
| Reconnect | Signs in to Xero again |
| Synchronise Tenant Rents | Sync tenancies (shown if rent books are switched on) |
| Synchronise Supplier Invoices & Commissions | Sync supplier items (shown if supplier settlements are switched on) |
| Synchronise Property Owner & Organisation Settlements | Sync settlements (shown if owner settlements are switched on) |
| The sessions table: Date started, Name, Errors, Status, Log, Actions | Every sync, newest first. Automatic syncs end in “(Automatic)” |
| Stop, Logs, Errors | Stop a running sync, read its full log, or list only its errors |
Sync options. Each sync form asks what to sync, then offers:
| Option | What it does |
|---|---|
| Only produce report | A dry run: lists what would change, and changes nothing |
| Force update (very slow) | Re-sends items even if COHO thinks they’re unchanged. Use it after changing mappings or tracking |
| Incremental - Only changes since [date]. | Ticked by default once a full sync has run. Only looks at what changed since the last error-free sync |
| Sync | Choices | Remove option |
|---|---|---|
| Synchronise Tenant Rents | Specific Tenancy, All tenancies in a specific property, All tenancies for this Xero connection | Remove tenancy data from Xero (one tenancy) |
| Synchronise Supplier Invoices & Commissions | A specific supplier, A specific property, All suppliers items for properties in this Xero connection. With all, Pull back supplier payments statuses only updates paid status | Remove supplier data form Xero (one supplier) |
| Synchronise Property Owner & Organisation Settlements | A specific settlement, A specific property owner, All settlements in this Xero connection | Remove settlement data from Xero (one settlement), Remove settlements data from Xero for property owner |
Remove options delete the invoices, payments and other data COHO created on that Xero contact. The contact itself stays.
Mappings
Section titled “Mappings”Mappings tell COHO which Xero account, tax rate, tracking option and contact to use. Each change saves straight away, with a message such as “Contact mapping updated”. Click Pull accounts, categories, and contacts first, or the lists are empty.
Chart of Accounts has four sections. Each has a column for Owned properties, Rent-to-Rent properties and Managed properties, so the same item can go to different accounts depending on how the property is held.
| Section | What you map | Typical choice |
|---|---|---|
| Settlements & supplier expenses | Each financial item category | Managed: often your “Property Control Account”. Costs your organisation pays and recovers from the owner use the Owned properties & disbursements column |
| Rent charges | Rent, Deposit, Holding deposit, Holding deposit kept, Deposit kept, Rent in advance, Arrears, and your “other” charge categories | Owned: an income account. Managed: your client money or property control account |
| Rent payment sources | How rent was paid (Standing order, Direct debit, Card payment, Cash, Bank transfer, Cheque, Housing benefit direct, From deposit, Credit, Other, Unknown) | A bank account, or an account that accepts payments |
| Bank accounts | Each bank account connected to COHO | The same Xero bank account. Show deleted bank accounts lists old ones |
Tax Rates. For each COHO rate (for example 20%), choose the Expense tax in Xero and Income tax in Xero. Add tax rate adds another percentage (1 to 100). If you don’t use VAT you can leave these blank.
Tracking Categories. Set up to two tracking options per item, to report by property or owner in Xero. Owned and rent-to-rent properties are listed under Owned Properties and Master-Lease / Rent to Rent Properties; managed properties are grouped by owner, with “Apply for all of [owner]”. Multi-let properties can also have one per room. Properties without ownership details are under Ownership Information Missing or Incomplete. Add option creates a new option in one of your Xero tracking categories.
Contacts. Link This organisation, your Suppliers, your Property Owners, and each tenancy (listed by property) to an existing Xero contact. Anything not linked gets a new Xero contact on its first sync, so map contacts that already exist in Xero before you sync.
Settings
Section titled “Settings”Click Edit on an integration, or Add Xero account for a new one.
| Setting | What it does |
|---|---|
| All properties / Properties owned by / Properties tagged with | What the integration covers. All properties means every property not covered by an owner or tag integration |
| Synchronise Rent Books | Yes: rent charges and payments go to Xero as invoices and payments |
| Synchronise Supplier Settlements | Yes: supplier costs go to Xero as bills payable |
| Synchronise Property Owner Settlements | Yes: owner settlements go to Xero as bills payable |
| Staging date (Sync items from) | Required for each sync you switch on. Today by default |
| Until | Optional end date. Nothing after it is sent |
| Create rent invoices days ahead | How early an unpaid rent charge becomes a Xero invoice: Default (7 days or if paid), 0 days ahead (Or if paid), 3, 10, 15 or 30 days ahead (Or if paid), or Only once a payment is reconciled |
| Automatic Xero sync | Yes to sync on a schedule |
| Frequency | Daily (every morning between midnight and 9am UK time) or Weekly (Monday mornings between midnight and 9am UK time) |
| Sync tenancies, Sync property owner settlements, Sync supplier items | Which syncs run automatically. Each only shows when that sync is switched on |
| Pause automatic syncs when the latest connection-wide sync has errors | Yes (default): an automatic sync type stops while its last full sync has errors, and you get an Action. No: it runs anyway. Click Change to see it |
| Assign actions for this Xero integration | Optional team member who gets this integration’s Actions |
Dates explained:
- Rent books: a charge is sent if its due date is on or after the staging date. A payment is sent if its date paid is too.
- Supplier items: by invoice date.
- Settlements: by the settlement’s dates.
Tenancies are included if they overlap the staging date and Until (or the next 24 months, if there’s no end date).
Statuses
Section titled “Statuses”A sync:
| Status | Meaning |
|---|---|
| Queued | Waiting to start |
| Running | In progress; the error and line counts update as it goes |
| Terminating | You clicked Stop; it’s finishing what it was doing |
| Completed | Finished. Check Errors for anything it couldn’t send |
| Aborted | Stopped, or stopped responding for 5 minutes |
The connection: “Expires in…” means it’s working; Expired means you need to reconnect.
Automatic sync, under Edit: “Last scheduler attempt” shows when the schedule last ran and the result: Triggered, Partially triggered (some sync types were paused by errors), Blocked, Skipped (a sync was already running) or Failed.
Who can use it
Section titled “Who can use it”| To | You need |
|---|---|
| See Connections & Synchronisations | Integrations (view) permission. Without Finances permission, the panel says “You do not have access to finances, but you can still manage the Xero integration below.” |
| Add an integration, connect, reconnect or disconnect | Integrations (edit) permission |
| See the mapping pages | Finances (view) permission |
| Change mappings, Pull accounts, categories, and contacts, Match tenancy contacts | Finances (edit) permission |
| Choose a specific settlement to sync | Settlements (view) permission |
Rules and automatic behaviour
Section titled “Rules and automatic behaviour”Which properties are included
- A property is only included if it’s active and uses Rent Collection.
- No overlaps: COHO won’t save two integrations covering the same owner, the same tag, or all properties (“Making this change will result in two active Integrations overlapping…”). A property that matches both an owner integration and a tag integration isn’t synced, and the sync reports an error.
- Ownership needed: rent is only sent for properties with ownership details (owned, rent-to-rent or managed).
Rent
- One invoice per charge. Its date and due date are set when it’s created and don’t change afterwards.
- VAT: split out only on owned and rent-to-rent properties, using your tax rate mapping. Managed rent is client money, so it’s sent with no VAT.
- When an unpaid charge is invoiced depends on Create rent invoices days ahead. A charge with a payment against it is always invoiced. With Only once a payment is reconciled, an invoice whose payment is later removed is deleted from Xero.
- Payments are only sent when they’re fully matched to charges. £0, negative and reversed payments aren’t sent.
- Payment account: a payment matched from a connected bank account uses its Bank accounts mapping; otherwise its Rent payment sources mapping.
- Onboardings: prospective tenancies are included. Their charges go to Xero once paid, or once due within your days-ahead setting.
- Changes in COHO: an edited amount updates the invoice (COHO removes and re-adds its payments to do this). A deleted or reversed charge has its invoice deleted or voided on the next sync. So does a charge removed from a recurring item or rent schedule; see Recurring items.
- Partly kept deposits aren’t supported. A deposit or holding deposit that’s fully kept is sent as a “kept” charge.
Suppliers
- Only financial items with a specific supplier, linked to a property in the integration, are sent. Misc. Supplier items aren’t. See Suppliers.
- If any item for a supplier can’t be sent, that supplier’s items stop for this sync and the error lists them.
Settlements
- Draft settlements aren’t sent. A deleted settlement’s bill is voided on the next sync.
- A bill already paid in Xero isn’t updated; COHO logs a warning instead.
Contacts
- COHO creates a contact the first time it needs one. For suppliers and owners it first looks for an existing Xero contact with the same email.
- Once created or linked, COHO doesn’t update a contact’s name or details. Change them in Xero if you need to.
Syncs
- Only one sync at a time per integration. A second one is refused until the first finishes.
- Errors don’t stop a sync. COHO skips what it can’t send, carries on, and lists each problem under Errors. Incremental syncs keep re-checking from the last error-free sync, so fixed items go through next time.
What COHO does automatically
- Runs automatic syncs on your schedule, if turned on. Automatic syncs are incremental and cover the whole connection.
- Pauses an automatic sync type when its last full sync had errors or was stopped (unless you set the pause to No), and creates an Action. The Action clears after a full sync of that type with no errors.
- Brings back paid status on every supplier or settlement sync:
- a settlement bill paid in Xero marks that settlement line Paid in COHO. An unpaid bill in Xero doesn’t change COHO;
- a supplier bill paid in Xero marks the financial item paid. A supplier bill that’s unpaid in Xero sets the item back to Unpaid, even if you marked it paid in COHO.
- Removes payments added in Xero that would overpay a COHO invoice, so it can add its own payment. See the caution below.
- Marks the connection disconnected if Xero refuses COHO’s access during a sync, for example if COHO was removed from Xero’s connected apps.
- Renews the connection each time it talks to Xero. If nothing talks to Xero for about 60 days, it expires.
What COHO doesn’t do automatically
- sync as soon as something changes. Changes go to Xero on the next sync;
- bring anything else back from Xero: invoices, payments, contacts or bank lines edited in Xero don’t change COHO;
- restore an invoice or bill that was deleted or voided in Xero;
- send deposit protection transfers, GoCardless fees, or anything not listed in “What goes to Xero”;
- remove a tenancy’s data from Xero when you delete the tenancy or deactivate the property. Use Remove tenancy data from Xero first.
What COHO sends you
| When | Who gets it | How |
|---|---|---|
| An automatic tenancy, owner settlement or supplier sync is paused by errors | The team member set under Assign actions for this Xero integration | An Action (“Resolve Xero tenancy synchronisation errors”, and so on), with an email or push notification depending on your notification settings |
Nothing is sent to tenants, owners or suppliers by the integration.
Related guides
Section titled “Related guides”- Xero integration: how-to: step-by-step instructions.
- Xero integration: troubleshooting: fixes and error messages.
- Finances & reports, Transactions, Recurring items, Suppliers, and Rent Schedules & Rent Collection.