How to Connect Xero

Connecting Biller Genie to Xero links the two systems through Xero's secure OAuth authorization flow. Once connected, your customers and invoices stay in sync between the two systems with no manual reconciliation. This article walks through the connection, what happens during the first sync, how to manage the connection day-to-day, and how to troubleshoot the most common errors.

Before you start

• Sign in to your Biller Genie merchant portal as an admin user.
• Have access to a Xero user account with Standard or Advisor permissions on the Xero organization you want to sync. Other roles (Invoice Only, Read Only) don't have permission to authorize Biller Genie. The user who connects becomes the "owner" of the integration — if that user is later removed from Xero, the connection breaks and a different Standard or Advisor user has to reconnect.
• Decide which Xero organization you want to connect — if you manage multiple Xero organizations under one Xero login, you'll choose the right organization during authorization.

Connect Biller Genie to Xero

1. In the Biller Genie merchant portal, click Add-ons Marketplace.
2. Select the Accounting Software category and click the Xero tile (or search for "Xero").
3. Click Install.
4. Click Connect to Xero. Biller Genie redirects you to Xero's authorization page.
5. Sign in to Xero with a user that has Standard or Advisor permissions on the organization you want to connect.
6. Select the Xero organization to sync, review the access Biller Genie is requesting (read and write access to contacts, invoices, accounts, items, and payments), and click Allow access.
7. Xero returns you to Biller Genie. Click Sync to start the first sync.

When the first sync finishes, you'll see a confirmation in the Xero add-on page and your Xero data will be available throughout the Biller Genie portal.

What happens during the first sync

After you authorize the connection, Biller Genie pulls your Xero data in this order:

1. Chart of Accounts — revenue, expense, bank, and other accounts, plus their types and active/archived status.
2. System items — Biller Genie creates the line items it needs for late fees, technology fees, and refunds in your Xero account (if they don't exist already).
3. Contacts (customers) — your active and archived contacts, including bill-to and ship-to addresses, email, phone, and any Contact Groups (which map to Customer Types in Biller Genie).
4. Invoices — open authorised invoices on the first sync; on subsequent syncs Biller Genie also tracks paid, voided, and deleted invoices.
5. Late fees and technology fees — Biller Genie applies any fees you've configured to outstanding Xero invoices.
6. Contact Groups — mapped to Biller Genie Customer Types for segmentation.

Because Xero's API is rate-limited to 60 requests per minute, the first sync paces itself with about one second between requests. For a typical merchant with a few hundred customers and invoices, the first sync takes 1 to 3 minutes. Larger company files take proportionally longer.

Sync settings after connecting

Open the Xero add-on page anytime to manage how Biller Genie interacts with your Xero account:

• Auto-sync — turn the ongoing background sync on or off. When on, Biller Genie syncs through Xero webhooks in near-real-time plus a polling fallback that runs at midnight, 5 AM, 11 AM, and 6 PM UTC. Turning it off pauses automatic updates between the two systems.
• Default Payment Account — set the Xero account where Biller Genie deposits collected payments.
• Default Commodity Code — set a default UNSPSC commodity code for items synced from Biller Genie.
• Integration Retention Interval — controls how often Biller Genie reminds you about unsynced data.

Managing the connection inside Xero

Xero also lets you view and manage every connected third-party app from within your Xero organization. From the Xero navigation, open Settings > Connected apps to see Biller Genie alongside any other connected apps. From there you can review what access has been granted, see when each app last connected, and disconnect any app directly from Xero.

For the canonical, up-to-date instructions on managing connected apps inside Xero, see Xero Central: Manage connected apps in Xero.

Disconnecting Xero from Biller Genie

1. In Biller Genie, go to Add-ons and select Xero.
2. Click Disconnect from Xero.
3. Biller Genie revokes the Xero authorization token, stops the background sync, and the Xero tile returns to its install state in the Add-ons Marketplace.

Disconnecting from inside Biller Genie also clears the authorization on Xero's side. If you disconnect from inside Xero instead (under Settings > Connected apps), Biller Genie detects the revocation on the next sync attempt and treats the connection as disconnected. Your existing synced data stays in Biller Genie; new syncs cannot occur until you reconnect.

Reconnecting after a Xero user is removed

The Xero user who originally connected the Biller Genie integration "owns" that connection. If that user is later removed from your Xero organization, the connection loses authentication and syncs start failing with an error like:

Xero API error calling GetAccounts: {"Type":null,"Title":"Forbidden","Status":403,"Detail":"AuthenticationUnsuccessful"}

To fix it, a different Xero user with Standard or Advisor permissions needs to reconnect:

1. Log in to Biller Genie.
2. Go to Add-ons > Xero.
3. Click Disconnect from Xero.
4. Click Connect to Xero and sign in with the new Standard or Advisor user.

Troubleshooting common errors

"Invoice # must be unique"

This error means an invoice with the same number already exists in Xero. Biller Genie can't export a duplicate invoice number. You have two options:

• Open the existing invoice in Xero and change its number so it no longer conflicts.
• Delete the invoice in Biller Genie, update your starting invoice number to one that doesn't conflict with existing Xero invoices, then regenerate the invoice.

"The discount rate '0.00' is invalid"

This error means the invoice contains a line item with a negative value. Xero doesn't accept negative line items on invoices and rejects the export. To resolve it: delete the invoice in Biller Genie, then re-invoice without using a negative line item. Discounts in Xero must be applied another way (using Xero's discount field on a line, or a positive line item that nets the bill correctly).

"To update fields on a paid invoice line item, you must supply a LineItemID"

This error occurs when you try to re-sync or update an invoice that has already been exported to Xero and marked as paid in Xero. Xero doesn't allow paid invoices to be updated through an integration. To resolve: in Xero, remove the payment from the invoice. Once the invoice is unpaid, re-sync from Biller Genie. Alternatively, make the necessary changes manually in Xero.

Sync token expired or "Authentication unsuccessful"

Xero access tokens expire periodically; Biller Genie normally refreshes them automatically. If a refresh fails (typically because the connecting user was removed from Xero or revoked permissions), the connection breaks. See the "Reconnecting after a Xero user is removed" section above.

Sync didn't pick up a recent change

Biller Genie syncs Xero changes through webhooks (near-real-time) and a polling fallback that runs four times a day. If a webhook is missed for any reason, the next scheduled polling sync catches it. You can also click Sync Now on the Xero add-on page to force an immediate sync.

Frequently asked questions

Does connecting Biller Genie change anything in my Xero?

Connecting itself doesn't change your Xero data — it only authorizes Biller Genie to read and write on your behalf. The first sync pulls your existing customers, items, accounts, and recent invoices into Biller Genie. Going forward, Biller Genie writes updates to invoices (mostly fee additions) back to Xero. See Using Xero in Biller Genie for the full data-flow details.

I selected the wrong Xero organization. How do I switch?

Disconnect using the steps above, then click Connect to Xero again. During authorization, Xero will let you pick a different organization from your login. Make sure you're selecting the correct organization before clicking Allow access.

My sync stopped working — what should I check first?

Three quick checks: (1) is the Xero add-on still showing as connected in Biller Genie? (2) Is the Auto-sync setting turned on? (3) Was the Xero user who originally connected removed from Xero recently? If yes, a different Standard or Advisor user needs to reconnect (see the section above).

Can I connect both Xero and QuickBooks?

No. A Biller Genie account connects to one accounting software at a time. If you switch from QuickBooks to Xero (or vice versa), you'd need to disconnect the first, then connect the second — and your existing synced data from the first system stays in Biller Genie but won't update from the now-disconnected system.

Related articles

• Using Xero in Biller Genie
• How to Connect QuickBooks Online
• Setting Global Customer Defaults
• Setting Invoice Defaults