Sync with Xero

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

Live sync needs the AI & integrations module and an owner or admin to connect it. On a plan without it, you can still use the Xero CSV export: 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

Sync checks Xero roughly every 30 minutes: it looks for quotes, invoices and supplier bills changed in Xero, reconciles payments Xero has recorded back into ONYX1, and pushes out any invoice ONYX1 owes Xero. A change made directly in Xero can take up to 30 minutes to appear here.

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 appear in ONYX1 as "from Xero" 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 is available on Pro and above.: your plan doesn't include AI & integrations. See Plans and what each includes.
• 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.