Skip to main content
Integrations & API

Xero accounting

Connect a Xero organisation to an Operating company, so your invoices and credit notes go to Xero and their status and payments come back.

Written By Mikko Karjalainen

Last updated 4 days ago

What the Xero integration does

The Xero integration connects one Operating company to one Xero organisation. Operating sends your invoices and credit notes to Xero, and Xero sends back their status and the payments recorded against them.

Invoices in Xero refer to Xero's own tax rates, items and contacts. So the integration also brings those records into Operating and links each one to its counterpart in Operating.

The integration has three features. Each feature has its own page on the connection, where you turn it on and change its settings:

  • Tax rates and items: imports the organisation's tax rates and items, which invoices pushed to Xero refer to.

  • Clients: imports the organisation's contacts as clients, and creates in Xero the clients an invoice pushed to it needs.

  • Invoices and payments: creates Operating's invoices and credit notes in Xero, and brings back their status and their payments. It needs the other two features to be on.

What syncs, and in which direction

In Operating

In Xero

Direction

Tax rate

Tax rate

Xero to Operating

Billable item

Item

Xero to Operating

Client

Contact

Xero to Operating, and Operating to Xero when an invoice needs the client

Invoice

Sales invoice

Operating to Xero

Credit note

Credit note

Operating to Xero

Invoice status

Invoice status

Xero to Operating

Payment

Payment on the invoice

Xero to Operating

Each feature's Data flow sets who writes each field of the records it syncs, as Who writes each field below explains. With the systems' defaults:

  • Tax rates and items: a record follows the system where it was created. A tax rate or item that Operating created from a Xero record is Xero's to change, so edit its details in Xero.

  • Clients: Operating and Xero both change a client's details, and the latest change wins.

  • Invoices: Operating writes the invoice, and Xero writes its status.

A field that only Xero writes is disabled in Operating. Hover over the field to see who writes it, for example "Name is written by Xero · Acme Ltd. Change it there."

When Xero keeps a company's list of tax rates or billable items, add new ones in Xero. They arrive in Operating with the next import. In Operating, adding one for that company is disabled, with a message such as "Xero · Acme Ltd keeps this company's tax rates. Add them there."

Operating imports tax rates, items and contacts when you turn a feature on, and then every day. It reads the status and payments of each invoice that is not settled yet as soon as Xero reports a change, and every 6 hours.

Before you start

In Operating, you need:

  • The Manage integrations permission to connect Xero, change its settings and map records. See Permission sets in Operating.

  • The right to edit the invoice (the Manage invoices permission) to save an invoice to Xero.

  • An invoicing currency on the company you connect. Without it, the Invoices and payments feature shows "Set the company's invoicing currency in Operating."

In Xero, you need:

  • A Xero user with access to the organisation. You sign in to Xero as this user and allow Operating's access.

  • Every currency you invoice in added to the organisation. Xero refuses an invoice in a currency the organisation has not added.

  • A sales account on each item you invoice. A line goes to the item's sales account in Xero.

How to connect Xero

  1. Go to Settings > Integrations and open Xero. The page lists each of your Operating companies.

  2. Next to the company, click Connect an account.

  3. In the dialog, choose the features to use. Every feature is ticked to start, and Xero is asked only for the access the ticked features need.

  4. Click Connect to Xero, sign in to Xero, and allow Operating's access.

  5. If your Xero user has more than one organisation, Operating shows Choose the account to connect. Click the organisation for this company.

Operating opens the connection's Overview tab. Nothing is imported until you turn on a feature.

You can connect each Xero organisation to one Operating company. To invoice from several companies, connect a separate organisation for each.

What the connection's page shows

Under the connection's name, a line shows its status, such as Connected, followed by the Operating company and details of the organisation, such as its base currency and country. Click Account details to see more, such as how Operating signs in to Xero.

When the status is Needs reconnecting, a notice above the tabs has a link to reconnect Xero. When it is Suspended, Operating has stopped the connection and nothing is exchanged. Contact support to resume it.

The page has three tabs: Overview, Mapping and Issues. The Overview tab shows what needs you first, then the Features list. Each feature in the list shows the direction it moves data (Into Operating, Out of Operating or Both ways) and when it last synced. Click a feature to open its page.

When something needs fixing, Needs you lists it with a badge and the button that fixes it:

  • Stopped: a feature that is on cannot run until you fix what blocks it. The button opens the fix, such as Map records, Open settings or Reconnect.

  • Warning: the feature runs, but one of its checks needs a look.

  • Failed: the last import or push of a feature failed. Click Run now to run it again, or Open feature.

  • 1 issue, 2 issues and so on: records that did not get through. Click Open issues to see them on the Issues tab.

When nothing needs you, the tab shows Everything's running and when the connection last synced. Before any feature is on, it shows Nothing is turned on yet.

How to set up the features

Turn the features on in two rounds, because Invoices and payments can be turned on only after its tax rates and items are mapped.

  1. On the Overview tab, open Tax rates and items.

  2. Turn on the feature's switch. It reads On after save until you save.

  3. Check the feature's settings. The settings are listed below.

  4. Click Save changes. Operating imports the tax rates and items.

  5. Click Overview to go back, and do the same for Clients. Operating imports the contacts.

  6. Map the imported records on the Mapping tab, as the next section says.

  7. Open Invoices and payments, turn it on, check its settings, and click Save changes.

A feature that cannot be turned on yet says why, and its readiness checks list what blocks it. For example: "3 billable items still need to be mapped."

The feature's page says why its switch cannot change now:

  • "Turn on Tax rates and items and Clients first; this feature uses what it imports." Invoices and payments needs the records the other two features import. Turn them on and save first. The message names only the features that are still off.

  • "Fix what blocks it before turning it on." A readiness check has not passed. Fix what the readiness checks list.

  • "Invoices and payments uses what this feature imports, so it stays on until Invoices and payments is turned off." Turn off Invoices and payments first.

  • "Operating has suspended this connection, so features can only be turned off." Contact support to resume the connection. Until then, you can turn a feature off but cannot change its settings.

A person without the Manage integrations permission sees You can view these settings. on a feature's page. That person can read the settings but cannot change them or turn the feature on or off.

Setting up the sync for Tax rates and items, Clients, and Invoices and payments

How to map tax rates, items and clients

The Mapping tab links each record imported from Xero to a record in Operating. It has a tab for each record type, such as Tax rates, Billable items and Clients, with the number of records still unmapped.

  1. On the Mapping tab, open Tax rates.

  2. For each record under To do, do one of these:

    • Click Accept to link it to the record Operating proposes.

    • Click Link to existing and choose the Operating record.

    • Click More and choose Create a new tax rate, or Ignore.

  3. Click Commit decided tax rate mappings. Nothing changes in Operating until you commit.

  4. Do the same on Billable items and Clients.

To decide on many records at once, select them and click Create new, Accept proposals or Ignore.

Operating proposes links where it finds a match, such as a client with the same VAT ID, invoicing email or name. Once no client is left unmapped, Operating creates a client for each new Xero contact, unless it matches a client Operating already has.

Map your existing clients before you send the first invoice. When Operating saves a client to Xero, it looks for a contact with the client's VAT ID. A client without a VAT ID gets a new contact, and Xero refuses it when another contact has the same name.

Mapping clients

Settings

Each feature's settings are on the feature's page. They show while the feature is on, and while it can be turned on. Click Save changes to save them.

What is imported:

  • Items to import: Items Xero sells, the default, or Every item, which adds the items you only purchase.

  • Contacts to import: Every contact but suppliers, the default, or Every contact.

  • A contact with an address Operating cannot store: an address in Operating needs a street line, a postal code, a city and a country. Choose Import the client without that address, the default, or Leave the client out until the address is fixed in Xero.

Records archived in Xero:

  • A tax rate archived in Xero: Archive it, the default, or Keep it active.

  • A client archived in Xero: Archive it, the default, or Keep it active.

How invoices are sent:

  • Push invoices as, Tax decided by and Sales account: these show their values and cannot be changed. Invoices go to Xero as drafts, and each line carries the tax rate mapped in Operating.

  • Without a sales account: what happens when a line's item has no sales account in Xero. Push as a draft, the default, or Wait for a sales account.

  • Invoice numbers come from: Operating, the default, or Xero. You can change it only until the first invoice is saved to Xero.

  • Link invoices back to Operating: on by default. The invoice in Xero links to its page in Operating, shown in Xero as Go to Operating.

  • Xero reference from: Xero has one reference field. Choose The invoice's reference, the default, or The purchase order number.

Status and payments from Xero:

  • An invoice approved in Xero: Mark it sent in Operating, the default, so its payments follow. Or Leave it for Operating to mark sent.

  • A document deleted in Xero: Void it, the default, or Keep it.

  • Overpayments and prepayments: Leave them out, the default, or Record them as payments of the invoice they are applied to.

  • Credit note refunds: Leave them out, the default, or Record them as payments of the credit note.

Who writes each field

Once a feature is on, its page has a Data flow section. It shows when each kind of record syncs, and who writes each field. Each field has a row with three columns:

  • Field: the field, such as a client's name.

  • Who writes it: the system or systems that set the field's value.

  • What happens: what this means for a record created in Operating and for one created in Xero.

A field that Xero does not carry shows "Not synced. Xero does not carry this field."

To change who writes a field:

  1. On the Overview tab, open the feature.

  2. In Data flow, find the field's row.

  3. Choose an option in Who writes it. Read What happens to check the result.

  4. Click Save changes.

Changing the data flow needs the Manage integrations permission.

Who writes it offers these options:

  • Operating only: set and edited in Operating. Not read from Xero or sent to it.

  • Operating, sent to Xero: set and edited in Operating, and sent to Xero.

  • Operating, then Xero: set in Operating when created. After that, only Xero's changes update it.

  • Xero: read from Xero, new and changed. Operating doesn't set it.

  • Where it was created: a record created in Operating is Operating's to change. A record created in Xero follows Xero.

  • Latest change wins: both change it, and each change is copied to the other. Operating asks you to confirm, because the systems overwrite each other's changes.

  • Custom: choose separately what Operating reads from Xero, what it sends to Xero and what Operating can do with the field.

An option that a field cannot take is greyed out, and the reason replaces its description:

  • "Not possible: Xero doesn't share this field." Operating cannot read the field from Xero.

  • "Not possible: Xero doesn't take this field from another system." Operating cannot send the field to Xero.

  • "Not possible: it can't change once created." The field is set only when the record is created.

Some fields are fixed once Xero has received the first record, such as the invoice number. Their row shows a lock and a note, such as "Fixed: Xero has received invoices already."

When your change gives a field a new writer and some records hold a different value, Operating shows Review how current values change with the number of records that differ. Choose one, then click Save data flow changes:

  • Apply now: Operating takes the new source's values on its next read, so the records match it.

  • Follow from now on: Operating keeps the values it has and takes only what the new source changes next.

To go back to the defaults for a kind of record, click its reset button, such as Reset clients to defaults. A kind of record that uses the defaults shows Systems' defaults.

When records sync

For each kind of record, the Data flow section has a From Xero line and a To Xero line. A line can hold these options:

  • On request: always available. Read one record with Refresh from Xero on its page in Operating, or save it to Xero from that page.

  • When Xero reports a change: Operating reads a record as soon as Xero reports a change.

  • An interval, such as Every 6 hours: Operating reads or sends the records on this schedule.

  • Create new clients: Operating's scheduled sending also creates the clients added in Operating. Only one connection can do this.

Tick or clear the options that have a box, then click Save changes. How often each sync runs is set by Operating. Contact support to change it.

How to send an invoice to Xero

Create the invoice in Operating as usual. See How to create and send an invoice.

  1. Open the invoice.

  2. Click Save to Xero. It is the invoice's main action until the invoice is in Xero.

  3. Open the invoice in Xero and approve it there.

When the save succeeds, Operating shows "Saved to Xero." The Accounting row of the invoice then shows Xero · Synced with the invoice's number in Xero. Click it to open the invoice in Xero.

Save invoice to Xero

When Operating saves an invoice:

  • Client: if the client is not in Xero yet, Operating saves the client first.

  • Lines: each line goes with its item, its amount before tax and its mapped tax rate. A line without a tax rate goes as tax exempt.

  • Status: the invoice arrives in Xero as a draft. Approving it in Xero posts it.

  • Number: the invoice keeps Operating's number, unless your settings let Xero number it.

If you edit the invoice after you save it, the page shows "Changes not in Xero yet." Click Update in Xero to send the change. Xero does not let a paid, credited or voided invoice change. Then Operating keeps the invoice as Xero booked it and shows "Xero kept it as booked, as it no longer lets it change."

To send a credit note, issue it in Operating, open it, and click Save to Xero. Operating saves the invoice it credits first, if that invoice is not in Xero yet. The credit note arrives in Xero as a draft, so approve it in Xero and allocate it to the invoice there.

How status and payments come back

Xero is where the invoice is approved and paid, and Operating follows:

  • Approved in Xero: Operating marks the invoice sent, with the default setting.

  • Paid in Xero: Operating adds each payment to the invoice, and marks the invoice paid once Xero reads it paid. The invoice's Activity shows Payment received with the amount.

  • Voided in Xero: Operating marks the invoice voided.

  • Deleted in Xero: Operating voids the invoice, with the default setting. Operating can void only an invoice that is sent, so a deleted draft of an unsent invoice shows as an issue until you mark it sent or keep it.

To read an invoice's status and payments right away, open the Accounting row's menu and click Refresh from Xero.

How to disconnect Xero

  1. Go to Settings > Integrations and open Xero.

  2. Next to the organisation, click its status, Connected, and choose Disconnect….

  3. Click Disconnect Xero to confirm.

You can also disconnect from the connection's Overview tab, under Danger zone.

Disconnecting stops every import, push and scheduled run, and Operating gives up its access to the organisation. Mappings and settings are kept, so connecting the same organisation again continues where it stopped.

Common errors and how to fix them

When a save or an import fails, the invoice's or the client's page shows the message. The connection's Issues tab lists every failed record with what fixes it. After you fix the cause, click Retry on the issue, or Retry saving to Xero on the invoice.

These are the messages you are most likely to see:

  • "Xero did not grant the access this needs. Reconnect Xero." The features you use need access you did not allow when you connected. Reconnect from the Xero page and allow the access.

  • "The Xero organisation disconnected Operating or was deactivated. Reconnect Xero." Operating was removed from the organisation's connected apps in Xero. Click Reconnect on the connection.

  • "This account is already connected for another company." The organisation is connected to another Operating company. Disconnect it there first, or connect another organisation.

  • "The Xero organisation has not added this invoice's currency. Add it in Xero's currency settings, then retry." Add the currency in Xero, then retry.

  • "A line's item has no sales account in Xero. Set one on the item in Xero, then retry." Set the sales account on the item in Xero, or set Without a sales account to Push as a draft.

  • "Xero no longer has an item a line uses. Import items again and map it, then retry." On the Overview tab, open Tax rates and items and click Run now next to Import billable items. Then map the item on the Mapping tab and retry.

  • "Another contact in Xero already has this name. Rename one of them, then retry." The client already has a contact in Xero. Link the client to that contact on the Mapping tab, then retry.

  • "More than one contact in Xero has this client's tax number, so Operating cannot tell which is this client. Map the client to one of them, then retry." Link the client to the right contact on the Mapping tab.

  • "Another document in Xero already has this number. Change one of the numbers, then retry." Change the number in Operating or in Xero.

  • "The date falls before Xero's lock date. Change the date, or the lock date in Xero, then retry." Change the invoice date, or the lock date in Xero.

  • "Xero no longer lets this document change, as it is paid, credited or voided there." Make the change in Xero, or issue a credit note in Operating.

When you click Save changes on a feature's page, Operating can refuse the save. Nothing is saved, and the message starts with the feature's name:

  • "… already sends this company's records. Turn off the feature that does it there first." Another connection, which the message names, already sends this company's records. Turn off that feature on the other connection, then save again.

  • "… already creates new clients. Turn “Create new clients” off there first, or leave it there." Only one connection can create new clients. Turn off Create new clients on the connection the message names, or leave it off here.

  • "A schedule that sends these records needs permission to change them. Ask someone who has it." Sending records on a schedule needs the permission to change those records, such as clients. Ask someone who has that permission to make the change.

If the scheduled sending of clients fails with "More than one connection is set to create new clients, so none creates them. Turn “Create new clients” off on all but one.", leave Create new clients on for one connection and turn it off on the others.

Related articles