Skip to content

Xero ​

Connect Xero to bring your customers into Rangefront Waste and keep your books in step. This page covers the whole flow. For the other providers, see integrations.

You need integrations.manage.

Set up ​

Open Admin > Integrations, add a Xero connection, then open it. The Xero setup list in the sheet walks through the steps and ticks each one off. You can also ask the assistant to connect Xero. It adds the connection, picks the organisation, runs the first import and turns on the automatic syncs, and you only sign in to Xero yourself. See Set up with the assistant.

If the sheet says you don't need a Xero app of your own, skip to step 4. This install has its own Xero app (see provider apps).

  1. Create an app at developer.xero.com. Choose New app, then Web app.
  2. In Rangefront, choose Edit and paste the app's client ID and secret. They are stored encrypted and never shown again.
  3. Add the redirect address from the sheet to your Xero app. Copy all of it. It starts with https:// and names this install's API host, which can differ from the console's address.
  4. Choose Connect Xero. Xero opens in the same window. Sign in as the person who owns the books, approve, and you come back to the sheet.
  5. If the sign-in reaches more than one Xero organisation, choose which one to use. Nothing syncs until you do. Changing the organisation later starts the next import from scratch.
  6. Choose Import customers from Xero. Use Test connection first if you want to see the organisation name Xero reports.
  7. Choose what syncs by itself.

Rangefront asks Xero for offline_access accounting.invoices accounting.payments accounting.contacts accounting.settings. These are Xero's newer, narrower scopes, and apps created after 2 March 2026 can only use them. An older app that still has accounting.transactions can set XERO_OAUTH_SCOPES to keep using it until Xero retires it in September 2027.

New Xero connections work both ways. A connection set to send only cannot import, and the sheet offers Allow both ways.

Import customers ​

The import reads your Xero contacts a page at a time. By default it takes customers only and skips archived contacts.

Each contact is matched to a customer in this order:

  1. The Xero link already saved on the customer.
  2. Email address, ignoring case. If several customers share it, the name decides.
  3. Exact name, ignoring case and punctuation. "Smith & Sons" matches "smith and sons".

A customer already linked to a different Xero contact is never matched again. When a match is unclear, the contact is skipped and listed in the run so you can sort it out by hand.

A match is linked, and only its empty details are filled in: email, phones, billing address, ABN and legal name. Nothing you typed is changed. Contacts with no match become new customers, with Xero's account number when it is free, its sales payment terms in days, and the postal address (or street address if there is no postal one).

The run reports how many were created, linked, updated and skipped, and why. Later imports ask Xero only for contacts changed since the last clean run. If any contact fails, the next run goes back to the same starting point.

Send customers ​

Customers sent to Xero are looked up there first, by account number, name and then email. One that already exists is linked, not created again. If the only match is archived, the customer fails with a message asking you to restore it in Xero. If Xero cannot be asked, nothing is sent.

Up to five customers are looked up one at a time. A bigger send reads your Xero contacts once, a thousand at a time, so it stays inside Xero's limit of 60 requests a minute.

Send invoices ​

Invoices go to Xero with each line's description, quantity, price, account code and tax type. Xero refuses an item code it doesn't have, so a line carries one only when you map it to a Xero item under Account codes. Drafts are not sent.

When Xero refuses an invoice, the run fails and shows Xero's reason, such as an account code it does not know. The invoice stays unsent and goes again on the next run.

Payments ​

Payments sync both ways when payments sync, whether you run it or it runs every hour.

  • Recorded here: a payment you record in Rangefront on an invoice that is in Xero goes to Xero, into the bank account in Payment bank account code, or your first bank account in Xero if that is blank. Each is sent once. Xero refuses one bigger than what is owing there, so a payment recorded in both places isn't counted twice. Untick "Send payments recorded here to Xero" in the sheet to stop this.
  • Recorded in Xero: a payment on an invoice Rangefront sent is applied to that invoice here. Payments for other Xero invoices are skipped, including older invoices with the same number as one of ours. A payment we sent comes back as the same payment, not a new one.

Credit notes and refunds ​

Run "Credit notes and refunds" from Sync now. It sends and imports.

  • A credit note recorded here goes to Xero and is applied to its invoice there, so the amount owing drops in both. If Xero won't apply it, for example because the invoice is already paid in Xero, the credit note stays open in Xero and the run says why. Apply it in Xero by hand.
  • A refund recorded here goes to Xero as a credit note paid out from the refund bank account, or your first bank account in Xero if that is blank.
  • A credit note made in Xero and applied to one of our invoices comes in as a credit note on it.
  • A refund made in Xero comes in when its credit note is applied to one of our invoices or its reference names one of our invoice numbers. Others are skipped.

Credit notes and refunds for invoices Rangefront never sent are skipped, not failed. Running it again never records one twice.

What syncs, and when ​

WhatDirectionWhen
CustomersXero to RangefrontImport customers, once a day if ticked, or when Xero tells us
CustomersRangefront to XeroSend customers
InvoicesRangefront to XeroSend invoices
PaymentsBoth waysEvery hour if ticked, or when Xero tells us
Credit notes and refundsBoth waysRun from Sync now, or when Xero tells us

Automatic syncs are two tick boxes on the connection. They need the connection to work both ways. A sync already waiting or running is not started twice.

Keeping the sign-in alive ​

Xero drops a sign-in that has not been used for 60 days. Rangefront renews every active Xero connection that has not been renewed in 30 days, once a night, so a quiet business stays connected. If Xero refuses a renewal for good, the connection shows Reconnect needed.

Webhooks ​

Webhooks are optional. Without them, changes arrive on the schedule above. With them, Xero tells us within a minute or so.

If the sheet says "Nothing to set up" under Changes from Xero, this install's own Xero app already sends them. Otherwise:

  1. In your Xero app, add a webhook using the address shown in the sheet. Tick Contacts, Invoices, Credit notes and Payments.
  2. Paste the webhook key Xero gives you into Edit, under Webhook key.
  3. Xero then checks the address. It passes when the key is right.

Contact changes queue a customer import. Invoice and payment changes queue a payments sync. Credit note changes queue a credit note and refund import. Changes in other Xero organisations are ignored. The work runs in the background, not while Xero waits.

Tokens and the server ​

The scheduler must be running for the nightly renewal and the automatic syncs. They are rangefront:integrations:refresh-xero-tokens and rangefront:integrations:auto-sync. See install.

Not covered ​

  • Importing Xero invoices, items or the chart of accounts.
  • Archiving a customer here when its Xero contact is archived.