Xero is a great cloud-based accounting platform that helps businesses manage invoices, payments, taxes, and financial records in one place. By integrating Onro with Xero, Onro sends completed order invoices, payments, and billing statements directly to Xero, reducing manual data entry and keeping your accounting up to date.
The Integration can help with:
Customer sync
Paid order invoice sync
Payment recording
Weekly, monthly, or manual invoice statement sync
Invoice cancellation and credit note handling
In this guide, we explain how to set up the Integration, understand how data is synchronized, and troubleshoot common issues.
The connection is one-way, from Onro to Xero, meaning Onro sends customer records, invoices, payments, and credit notes to Xero, and Xero does not send any accounting changes back.
Before You Begin
Before connecting Onro with Xero, make sure you have an active Xero account. You'll also need to prepare a few configuration values from your Xero account, as some settings require information to be copied directly from Xero. Depending on your accounting setup, you may need help from your accountant for some fields, especially account codes, tax rates, and payment/clearing accounts.
Required information from Xero:
Difference between Sales Account Code and Clearing Account Code
Sales Account Code and Clearing Account Code both are needed for the integration and are not two versions of the same thing. They are different types of Xero accounts that serve two unrelated purposes:
Sales Account Code is an Income account. It classifies the type of revenue in your Profit and Loss (P&L) report and is used on each invoice line item.
Clearing Account Code is a Bank account. It tracks where the payment is held and is used only for the payment transaction, not on invoice lines.
This distinction is important because Xero only allows payments to be recorded against a Bank-type account. If you set the Clearing Account Code to a regular Income, Expense, or Asset account, Xero will reject any payment Onro attempts to record.
When you or your accountant create the Clearing Account in Xero's Chart of Accounts, make sure the Account Type is set to Bank. This is easy to miss because a "Clearing Account" does not sound like a bank account, but Xero requires it to be a Bank-type account for payment recording.
How to get Sales Account Code
The Sales Account Code is the Xero revenue account where your delivery income is recorded. Every invoice line Onro creates will be booked to this account.
For example, in many Xero accounts, 200 is used for Sales. When Onro creates an invoice in Xero, each order line will use this account code.
To find the sales account code, navigate to your Xero dashboard and, from the top menu, select Accounting→ Chart of accounts.
On this page, find the revenue or sales account your accountant wants to use for delivery income and make sure to copy the Code, not the account name.
If you are not sure which account to use, ask your accountant: “Which Xero sales/revenue account should we use for delivery income from Onro?”
Example:
Account name: Sales
Code: 200
How to get Xero Tax Rate Name
The Xero Tax Rate Name is the tax rate name you want to use for Onro invoices.
To find the tax rate name, open this link or, from the top menu, select Tax→ Tax settings, and on the settings page, find Manual tax rates and click on it.
Select the tax rate you want to use for Onro invoices, copy its name exactly, and save it somewhere. Make sure to copy the full name, not just the percentage.
If you do not have the tax rate you need, you can create a new tax rate in Xero first, then copy its name.
Correct example: TOTAL SALES TAX 18%
Wrong example: 18%
How to get Clearing Account Code
The Clearing Account Code identifies the Xero account where payments are recorded. Onro uses this code whenever it records a payment in Xero, so the account needs to exist and be set up correctly in Xero before you provide the code.
A clearing account works as a temporary holding account: payments land there first, then get reconciled against an invoice or matched to a bank deposit. This keeps different payment types organized and makes reconciliation easier.
Example use cases:
Wallet payment
Cash payment
Card/online payment
Any order payment that should be recorded against a clearing account
To find the clearing account code, navigate to your Xero dashboard and, from the top menu, select Accounting→ Chart of accounts.
Find the account your accountant wants to use for payments( If the account does not exist yet, create it here) and copy the Code, not the account name.
Ask your accountant which account should be used.
How to get Branding Theme Name
The Branding Theme Name determines which Xero invoice template will be used for the invoices. It controls the design and layout that will be applied to the invoices. You can either create a new branding theme or use an existing one by navigating to Settings → Invoice Settings in Xero.
This affects how the invoice PDF looks in Xero.
From the top-left, select the Account(Icon) → Settings, and on the settings page, select Invoice settings.
Find the branding theme you want to use, copy the theme name exactly, and save it somewhere.
Setting Up the Xero Integration
Now that you have the necessary information, it's time to set up the connection with Xero.
Step 1: Configure the settings in Onro
To do so, open the Admin Center and follow the path below:
Admin Center → Settings → Integration → Accounting → Xero → New
Here, fill in the required fields as explained below:
Title: Enter a meaningful title for this Xero connection(Xero organization's name is a suitable option to enter here)
Business: The Integration needs to be connected through a Business Customer account. The specific account you select doesn't affect which data is synced to Xero. Once the Integration is connected, customer data from all accounts will be sent to Xero.
The selected Business Customer account is only used to establish and authorize the connection.
Sales Account Code: Enter your sales account code that you obtained in the previous step here.
Xero Tax Rate Name: Enter the tax rate name that you obtained in the previous step here.
Line Amount Types: This tells Xero whether the amount Onro sends for each order line is the price before tax, or the price with tax already included. It controls how Xero calculates the tax on the invoice. Available options are:
- Exclusive(Recommended):
The amount Onro sends would be the subtotal, before tax. Xero applies its own tax on top of that amount, then calculates the final total.
Example: Onro sends 83.77 as the subtotal amount, and Xero adds 18% tax. The tax amount is 15.11, so the invoice total becomes 98.88.
- Inclusive:
The amount Onro sends is treated as the final total, tax already included. Xero doesn't add anything on top. It just works out how much of that amount was tax.
Example: Onro sends an invoice total of 15.86, which already includes tax. Xero calculates how much of that total is tax. With an 18% tax rate, it records 2.42 as tax and 13.44 as the amount before tax. The total stays 15.86.
- NoTax:
No tax is applied at all. The invoice total in Xero matches the amount Onro sent, exactly.Clearing Account Code: Enter your clearing account code that you obtained in the previous step.
Paid Order Invoice Status: This is the status Onro should use when creating invoices in Xero for completed orders. Available options are:
- AUTHORISED (Recommended):
The invoice is finalized and ready. If Paid Order Record Payment is also enabled, Onro will separately record a payment against it, which brings it to Paid status in Xero.- DRAFT:
The invoice is created in Xero but held back for review. Your accountant checks it before finalizing, and Onro won't record a payment on it until then.- SUBMITTED:
The invoice is sent for approval but not yet finalized. Someone still needs to authorize it in Xero before it can be marked as paid.
Status Comparison👇
Status | Where it appears in Xero | Can Onro record payment automatically? | Best for |
AUTHORISED | Awaiting Payment / Approved invoices | Yes, if Paid Order Record Payment is enabled | Recommended for most users when invoice data is ready |
DRAFT | Draft invoices | No | Accountant review before approval |
SUBMITTED | Awaiting Approval | No | Companies with an invoice approval process |
Use AUTHORISED if you want Onro to create the invoice and automatically record payment when payment recording is enabled.
Use DRAFT or SUBMITTED only if your accountant wants to review or approve invoices manually in Xero first.
If the invoice is created as DRAFT, Onro will not record a payment against it automatically.
Branding Theme Name: Enter the branding theme name that you obtained in the previous step.
Order Type: Choose which Onro order types should be synced with Xero. Multiple order types can be selected here.
Onro will sync eligible completed orders for all selected order types.
Paid Order Sync Enabled: Turn this option on to have Onro automatically create invoices in Xero for each completed order. Once enabled, whenever a delivery order is completed in Onro, a corresponding sales invoice will be created in Xero.
Turn this off if you don't want each completed order to be automatically sent to Xero and created as an invoice.
Paid Order Record Payment: Turn this on if you want Onro to automatically record payments for paid orders in the corresponding Xero invoices.
When enabled:Onro creates the invoice in Xero.
If the invoice status is AUTHORISED, Onro will automatically create the invoice with the Paid status.
The payment is recorded using the configured Clearing Account Code.
Disable this option if you only want Onro to create invoices and prefer that payments be recorded or reconciled manually by your accountants.
This only applies to paid orders and does not apply to Onro invoice statements sent to Xero.
Invoice Statement Sync Enabled: Turn this on to automatically sync your Onro billing cycle statements (weekly, monthly, or manual) to Xero as invoices.
When this option is enabled, every time an invoice is generated in Onro, regardless of the billing cycle, it will be automatically sent to Xero.
After providing this information, click the Submit button.
Step 2: Xero Configuration
Now, on the Integrations page, click the Actions button and select Connect. You'll then be redirected to Xero to complete the setup.
After being redirected to Xero, you’ll be prompted to log in if you’re not already signed in. If you have access to multiple Xero organizations, select the organization you want to connect with, then click Allow access to authorize the connection.
Step 3: Verify the connection
After granting access, Xero will redirect you back to Onro. The Integration status should change to Connected. If it does not, something may have gone wrong during the setup process. In that case, repeat the steps and try connecting again.
What Gets Synced
Customers Sync
When a new customer is created in Onro, Onro creates or updates a matching Xero Contact. This applies to both individual and business customer types.
If a matching contact already exists in Xero, Onro reuses or updates that record. No duplicate contact is created.
Individual customers Info
Field | Sent |
Name | Always |
Always | |
Phone | Always |
Address | Always |
Tax/VAT number | Only if available |
Example:
Individual Customer registers in onro 👇
The corresponding contact is automatically created👇
Business customers Info
Field | Sent |
Business name | Always |
Contact person name | Always |
Always | |
Phone | Always |
Address | Always |
Tax/VAT number | Only if available |
Business Customer registers in Onro 👇
The corresponding contact is automatically created👇
Paid Orders Sync
This applies to completed orders (orders with Done and Delivered statuses in Onro). When an eligible order is completed in Onro, a sales invoice is automatically created in Xero.
The invoice can include the following information:
Customer's info
Order type
Order amount
Tax rate
Sales account
Due date
Branding theme
Reference (the Onro order code)
If Paid Order Record Payment is turned on in the Integration settings, Onro can also record payments in Xero. This allows the invoice status to be automatically updated to Paid in Xero by Onro.
Onro creates Xero sales invoices only and does not create Xero bills or sync data from Xero back to Onro.
The invoices generated for each paid order use the due date configured in your Xero settings. If you need to change the due date, you can update it directly in Xero.
Invoice Statements Sync
Invoice Statement Sync handles billing-cycle invoices created in Onro, the kind that cover many orders at once instead of one invoice per order. This applies to weekly invoices, monthly invoices, and manual invoices.
This is the option to use when you bill a customer for a batch of orders together, rather than invoicing each delivery individually.
When a billing-cycle invoice is created in Onro, Onro sends it to Xero as a matching invoice with everything needed to reflect that billing period:
Customer information
Statement period
Order lines
Extra charges
Service fees
Tax
Due date
Branding theme
Reference (the invoice code in Onro)
The due date shown here comes directly from the invoice settings configured for the billing statement in Onro.
If a statement was already synced before, Onro won't create it again in Xero. This keeps you from ending up with duplicate invoices for the same billing period.
Invoice Paid Sync
When a billing-cycle invoice is marked as paid in Onro, that payment gets recorded against the matching invoice in Xero too. The payment is posted to whichever account you set as the Clearing Account Code.
This is what lets your accountant look at Xero and immediately see that the invoice has been paid, without having to manually match it up on their end.
How the payment amount is calculated
Onro doesn't recalculate or apply tax when recording a payment. Xero already knows the invoice's full total, since it added its own tax when the invoice was created. Onro simply tells Xero how much has been paid so far.
Partially Paid: Onro records only the new amount paid since the last update, not the running total. For example, if a customer has now paid 90.02 in total and Onro previously recorded 85.02, only the 5.00 difference is sent to Xero. This avoids duplicate payments.
Paid: Onro records whatever amount remains to bring the invoice to zero, including any tax Xero added on top of the original amount. This is why the final payment can be a slightly different number than what the customer actually paid in Onro; it's closing out the exact remaining balance in Xero.
This behavior is what keeps the invoice accurately marked as paid in Xero, even though the totals along the way may not match the amounts in Onro one-for-one.
Cancellation Sync and Refund Handling
Onro also handles cancelled orders and cancelled invoice statements, but what actually happens in Xero depends on the invoice's status there:
If the invoice is unpaid
Onro voids the invoice in Xero.
If the invoice is already paid
Xero does not normally allow a paid invoice to be voided directly. If the entire statement invoice is cancelled, Onro automatically creates a credit note. If only part of the statement is cancelled (some but not all orders on it), Onro flags it for manual review instead, since it can't safely split a partial credit note out of a multi-order invoice.
Paid order cancellation
For a single paid order invoice, Onro can create a credit note and record a refund transaction in Xero. This does not refund money through Stripe or a bank account. It only records the refund in Xero for accounting. The real money refund should still be handled by your payment provider, bank, or accountant's process.
Statement invoice cancellation
For weekly, monthly, or manual statements, some cancellations may need manual review, especially if only part of the invoice is cancelled.
This is because a single statement invoice may include multiple orders.
How to Disconnect Xero
Disconnect in Onro:
To disconnect Xero from Onro, go to the Admin Center and follow the path below:
Admin Center → Settings → Integrations → Accounting → Xero
Disconnect in Xero:
In the Xero dashboard, navigate to the following path:
Settings → Connected apps → Find Onro → Disconnect
What happens after disconnecting:
Onro will stop sending new data to Xero.
Existing Xero invoices, contacts, payments, and credit notes will remain in Xero.
Onro will remove the active Xero connection from this Integration.
You can connect again later if needed.
Troubleshooting
⛔Xero is not connected
Problem:
The Integration status shows disconnected, or sync does not happen.
What to do:
Make sure Xero was connected successfully.
Reconnect Xero from the Onro Xero integration page.
Make sure the correct Xero organization was selected during connection.
⛔Data is going to the wrong Xero organization
Problem:
Invoices or contacts are going to the wrong Xero organisation.
What to do:
Disconnect Xero from Onro.
Connect again.
During Xero authorization, select the correct organisation.
⛔Sales account code is wrong
Problem:
Xero rejects the invoice or puts revenue in the wrong account.
What to do:
Go to Xero → Accounting → Advanced → Chart of accounts.
Check the correct revenue account code.
Copy the account code into Onro.
Ask your accountant if you are not sure.
⛔Tax rate is not found
Problem:
The tax rate name in Onro does not match a Xero tax rate.
What to do:
Go to Xero → Accounting → Advanced → Tax Rates.
Copy the tax rate name exactly.
Paste it into Onro.
⛔Clearing account code is wrong
Problem:
Invoice is created, but payment cannot be recorded.
What to do:
Go to Xero → Accounting → Advanced → Chart of accounts.
Find the bank or clearing account.
Copy the account code into Onro.
Make sure the account can be used for payments.
Ask your accountant if you are not sure which account to use
⛔Invoice is created, but payment is not recorded
Possible reasons:
Paid Order Record Payment is turned off.
Invoice status is DRAFT or SUBMITTED.
Clearing Account Code is missing or wrong.
Xero rejected the payment.
The invoice is not AUTHORISED.
What to do:
Check Paid Order Record Payment setting.
Check Paid Order Invoice Status.
Check Clearing Account Code.
Ask your accountant if payments should be recorded automatically or manually
⛔Customer details are missing on invoice PDF
Problem:
Xero invoice templates usually show the customer address block. If the customer does not have address information, Xero may only show the customer name.
What to check:
Make sure the customer in Onro has a name, email, phone, and address.
Make sure the customer was synced to Xero.
Check the Xero contact details.
⛔Branding theme is not applied
Problem:
The invoice PDF does not use the expected template.
What to check:
Go to Xero → Settings → Invoice settings.
Check the branding theme name.
Copy the name exactly into Onro.
If the name is empty or does not match, Xero may use the default branding theme.
⛔Invoice statement does not sync
Problem:
The invoice statements created in Onro don't sync with Xero
What to check:
Make sure Invoice Statement Sync Enabled is turned on.
Make sure Xero is connected.
Make sure the Sales Account Code is correct.
Make sure the customer exists and has correct information.
Check that the statement was sent or created from Onro.
⛔Paid order does not sync
Problem:
Paid orders in Onro don't sync with Xero
What to check:
Make sure Paid Order Sync Enabled is turned on.
Make sure the order type is selected in the Order Type field.
Make sure the order is completed.
Make sure Xero is connected.
Make sure Sales Account Code, Line Amount Types, and invoice status are set.
⛔Why is the price different in Onro and Xero
Problem:
The total shown in Onro is different from the invoice total created in Xero.
What's happening:
This is usually expected, not an error, and it's not just "Xero adds tax on top." Onro's own total can already include Onro's own internal tax on some items (like a service fee) while not taxing others (like the delivery order lines) at all. Xero ignores Onro's internal tax handling completely and instead calculates its own tax, using your configured Xero Tax Rate Name, applied evenly across every line — orders and fees alike. So the difference usually comes from two things at once: Xero taxing lines that Onro's own total never taxed, plus Xero's tax rate possibly differing from whatever Onro used internally.
Example (real invoice):
Onro order lines: 77.52 (not taxed by Onro)
Onro service fee: 6.25, with Onro's own tax of 1.25 already included
Onro total: 85.02
Xero subtotal (orders + fee, before Xero's tax): 83.77
Xero tax at 18% (Xero's configured rate, applied to everything): 15.11
Xero invoice total: 98.88
What to do:
Treat the Xero invoice as the source of truth for tax — it's the accounting-compliant figure, not Onro's own total.
Check your Line Amount Types setting. With Exclusive (recommended), Xero treats the Onro line amounts as pre-tax and adds its own tax on top — this is expected to produce a higher total than Onro's number.
Double-check the Xero Tax Rate Name is the rate you actually want applied — a wrong or outdated tax rate name can make the gap look bigger than it should be.
When recording payments, Onro always accounts for this automatically. Partial payments record only the newly paid amount; the final payment closes out whatever balance remains in Xero, including any tax Xero added. The invoice still ends up correctly marked as Paid, even though the running totals differ from what you see in Onro along the way.
⛔Refund recorded in Xero, but customer wasn't actually refunded
Problem:
A credit note shows up in Xero after a cancellation, but the customer says they haven't received their money back.
What's happening:
This is expected. Onro creates a credit note in Xero to keep your books accurate, but it doesn't move any actual money. Recording the refund and sending the money back are two separate steps.
What to check:
Confirm the real refund through your payment provider, bank, or accountant, separately from Xero. Onro doesn't send refunds through Stripe or a bank account.
If the customer paid by wallet or card through Onro, check that Onro processed the refund on its own side. That's a separate step from what happens in Xero.
⛔ Cancelled paid order didn't create a credit note
Problem:
An order was cancelled after the invoice was already paid, but no credit note appears in Xero.
What's happening:
For a single paid order, Xero won't let a paid invoice be voided directly, so Onro handles this automatically by creating a Credit Note and recording a refund against it. This should always succeed for a single order; if it didn't, something failed along the way (most commonly an invalid or missing Clearing Account Code, since the refund step needs it) rather than the case needing manual review.
What to do:
Check the Clearing Account Code is valid and points to a usable bank account in Xero.
Confirm the invoice status in Xero before cancellation. If it weren't actually paid yet, Onro would have voided it instead of creating a credit note.
If the Clearing Account Code looks correct and nothing appears in Xero, contact support with the order code so we can check the actual sync error.
⛔ Statement invoice cancellation is stuck or needs manual review
Problem:
A weekly, monthly, or manual statement was cancelled in Onro, but nothing changed on the matching invoice in Xero.
What's happening:
A statement invoice can cover many orders at once. If only part of that statement is being cancelled, rather than the whole thing, Onro can't always resolve it automatically and leaves it for manual review instead.
What to do:
Check whether the whole statement was cancelled or just some orders within it. Partial cancellations are the most likely to need manual handling.
Have your accountant review the statement invoice directly in Xero and adjust it manually if needed.
⛔ Payment amount in Xero doesn't match what the customer paid
Problem:
The payment recorded against an invoice in Xero looks smaller than the amount the customer actually paid.
What's happening:
This is usually expected for invoices paid in installments. When an invoice is Partially Paid, Onro only records the new amount paid since the last update, not the running total. Once the invoice is marked Paid in full, Onro records whatever remains, including any tax Xero added, to close the balance out to zero.
What to do:
Look at the invoice status in Onro (Partially Paid vs. Paid) alongside the payment history in Xero. The individual payments should add up to the full invoice total once it's fully paid.
If the invoice is marked Paid in Onro but Xero still shows an amount due, check that the payment sync actually went through rather than assuming the numbers are wrong.
Can't find your issue? Feel free to contact us at [email protected], and we'll be happy to help.