Skip to content

Sync with Xero

Connect your Xero organisation and choose which way quotes and invoices flow between it and ONYX1.

For ownersLast reviewed
On this pageBefore you start

Live Xero sync brings quotes in from Xero, moves invoices in and out depending on what you choose, and marks an invoice paid here automatically once it's reconciled in Xero. Connecting an organisation never starts anything moving on its own: you connect, then you choose what syncs and which way.

Before you start

Every plan includes live sync. An owner or admin connects it. If you'd rather not connect, you can use the Xero CSV export instead: see Export invoices to Xero as a CSV.

Connect your organisation

  1. Open Settings → Xero.
  2. Select Connect to Xero. You're sent to Xero to approve access, and can disconnect at any time.
  3. Pick your organisation on Xero's screen. If your business's own live organisation isn't offered by name, don't approve one of Xero's demo organisations instead: ONYX1 blocks syncing for anything that looks like a demo org, because demo data must never reach your real books.
  4. Back in ONYX1, confirm that the organisation named is the one you want to sync.

If Xero doesn't approve the connection and you weren't shown an approval screen, sign in to Xero in the same browser first, then try again.

If you reconnect while a sync is running, ONYX1 keeps the current organisation safe and asks you to try again in a few minutes: Xero is syncing; try again in a few minutes.

Choose what syncs, and which way

Set Quotes and Invoices separately. Each row offers the same four buttons: Off, Xero → ONYX1, ONYX1 → Xero and Two-way. Every entity starts Off: connecting an organisation never moves data on its own.

For Invoices, all four work as the buttons say: nothing moves, invoices flow in, invoices flow out, or both. In Two-way, the change that syncs last wins, with two exceptions: an invoice voided in ONYX1 stays voided whatever Xero shows, and an invoice raised in ONYX1 and marked paid here stays paid even while Xero still shows it as owing. The inbound setting also controls the read-only supplier-bill pull described below.

For Quotes, only the inbound half works today: a quote only ever arrives from Xero, it is never sent out. Xero → ONYX1 and Two-way both turn that inbound flow on; Off and ONYX1 → Xero both turn it off, since there is nothing yet built to push out under either one. Whichever you choose for Quotes, a quote you raise in ONYX1 is never sent to Xero.

Select Save sync settings once you've set both.

Check invoice amounts

Only the owner can refresh amounts on invoices that came from Xero. The check is available when Xero is connected, the organisation is confirmed, and invoice sync is set to Xero → ONYX1 or Two-way.

  1. Open Settings → Xero.
  2. Select Check invoice amounts with Xero.
  3. Review the ONYX1 amount ex GST, Xero amount ex GST and difference for each invoice. The panel also tells you how many rows are already correct.
  4. Select Update N invoices after reviewing the differences. Only the three Xero amount fields are updated; the invoice status, lines and links stay unchanged.

Large checks run in batches. If Xero rate-limits a batch, a temporary Xero error occurs, or the safe run time is reached, the panel shows a partial result and a resume point. Select Check next batch after the issue clears; failed rows are not reported as complete.

Pull supplier bills and map job-cost accounts

When the Invoices direction includes Xero → ONYX1, ONYX1 reads supplier bills from Xero. A supplier bill is stored as a job cost when it is linked to a job and its account code is mapped as a job cost. It is never imported as sales revenue, and ONYX1 never edits the bill in Xero. Job-cost amounts use ex GST values.

In Settings → Xero, the Xero account mapping section lists the expense and revenue account codes cached from Xero. ONYX1 guesses Job cost from account names such as hire, equipment, materials, subcontract, freight and consumables. Review the guess, then turn each Job cost switch On or Off. Select Refresh accounts to read the account list again. Only an owner or admin can change this mapping.

Connections made before the account-list permission was added show Reconnect Xero to allow bills. Existing invoice sync remains safe until you reconnect. After reconnecting, supplier bills and account mapping use the added read-only permission.

If a supplier bill does not contain certain job evidence, it is not allocated automatically. The owner or admin queue lets you match it to a job, record it as Overhead (not job cost), or choose Not for a job. For the full matching and reconciliation workflow, see Reconcile Xero bills and invoices with your jobs.

An issued or paid invoice linked to a job is checked against the mapped job-cost account codes. If an invoice line has no matching recorded cost, ONYX1 creates one job reconciliation item for that job. You can link a suggested supplier bill, add the missing cost from the invoice line, or mark the line Not a cost for this job with a reason.

Invoices only: nothing historical is sent

The first time you turn invoice sync to ONYX1 → Xero or Two-way, only invoices issued from that moment on are ever sent. Anything you'd already invoiced before then stays in ONYX1 and is never pushed, so nothing you've already entered in Xero by hand gets duplicated. The panel shows the exact date from which invoices are sent.

If you turn invoice sync off and later back on, ONYX1 asks what to do with anything issued while it was off. Choose Send them to Xero if you didn't enter them there yourself while sync was paused, or Leave them out, sync from now if you did, since sending them would create a duplicate of each one. Whichever you choose, the panel then states the exact window that was left out, if any.

If you also use the Xero CSV export, it's fine for invoices from before your sync start date, since those never sync. Filter out anything dated on or after that before importing the file: syncing writes a different invoice-number format, so Xero won't spot a duplicate on its own.

Where payments post

Once connected, set a Payment bank account code: the account in your Xero chart of accounts that pushed payments post against (often 090 for a default bank account). Invoices sync either way, but until you set this, payments are held back; the invoice itself says why.

Reconnect or disconnect

A connection that's about to expire, or has already lapsed, shows a warning; select Reconnect to renew it (Xero drops an unused connection after 60 days). Select Disconnect from Xero at any time to stop syncing altogether, then confirm when asked.

How it runs

When invoice sync is set to Xero → ONYX1 or Two-way, ONYX1 fetches an invoice as soon as Xero reports a change to it. If your organisation isn't already syncing, the first fetch starts straight away and each one after it starts five seconds later, so at most 12 a minute. Ten changed invoices are usually all in ONYX1 in under a minute when Xero answers promptly.

A big batch takes longer, because one pass stops after 90 seconds and can fit at most 18 fetches. If 30 invoices change at once, ONYX1 applies 18 in the first pass and the other 12 in a later catch-up pass. Catch-up passes run every two minutes, so the last invoice arrives between about two and a half and four and a half minutes after Xero reported it. A sync already running for your organisation, or a slow answer from Xero, adds to that. Quotes and supplier bills are not part of this faster route.

If a fetch fails, for example because Xero can't be reached, ONYX1 tries that invoice again after about 2 minutes, then 10 minutes, 30 minutes and 2 hours. If the fifth attempt also fails, about 2 hours 45 minutes after the first, ONYX1 stops retrying that change. The check below still picks up an approved, paid or voided invoice, but a draft invoice updates only when Xero next reports a change to it.

Every 30 minutes, ONYX1 also checks Xero for changed quotes, approved, paid and voided invoices, and supplier bills. It reconciles payments Xero has recorded back into ONYX1 and pushes any invoice ONYX1 owes Xero.

Numbers on documents from Xero

An invoice or quote that came from Xero keeps its Xero number in ONYX1. A Xero invoice numbered INV-1028 shows as INV-1028 everywhere ONYX1 shows a number: the lists, the invoice or quote itself and its PDF, emails, the client portal, the iPhone app, exports and search. Search for that number to find it. If the number changes in Xero, the next sync changes it here too.

Invoices and quotes raised in ONYX1 keep their ONYX1 numbers, including invoices ONYX1 sends to Xero.

When Xero changes an invoice

A later pull can update an invoice's status, due date, header amounts and payments. When Xero supplies the subtotal, GST and total, those header amounts are used throughout ONYX1, including the invoice page, invoice list, PDFs and email, customer portal, Reports and its ledger CSV, invoice register CSV and overdue reminders. The accounting files in Settings → Exports are separate: the MYOB export lists the stored line items for each included invoice, including invoices that came from Xero. The lines held in ONYX1 may not add to the Xero header if Xero used a discount or a line type ONYX1 does not import. This is expected because Xero is the source of truth for an invoice it raised.

Payments recorded in Xero show a Xero badge in ONYX1 and cannot be removed there. If you edit a Xero draft in ONYX1, ONYX1 uses the new lines until the next Xero header arrives.

If something goes wrong

  • Xero sync isn’t part of your current plan.: every plan includes Xero sync, so this shouldn't happen. Email support@onyx1.app and we'll check your workspace.
  • Only an owner or admin can connect Xero.: ask one of them to connect it.
  • Syncing is blocked: the connected organisation looks like one of Xero's demo organisations. Disconnect and reconnect your real organisation.
  • Reconnect Xero to allow bills: the connection predates the read-only Accounts permission. Select Reconnect Xero in Settings → Xero; existing invoice sync is not interrupted while you decide.
  • Xero is syncing; try again in a few minutes.: another sync is still running. Wait a few minutes, then try again.
  • That Xero organisation is already connected to another ONYX1 account.: disconnect it there first, or pick a different organisation.
  • An invoice isn't moving: check that its direction isn't set to Off, and that the connection's status isn't needs reconnecting or access revoked. A quote not moving is expected unless its direction is Xero → ONYX1 or Two-way; see "Choose what syncs, and which way" above.