The Xero integration sends your contacts, invoices, bills and credit notes from Omono to Xero, so you do not enter them twice. Admin Users set it up under Settings → Connect.
What syncs
The sync sends data from Omono to Xero, in this order:
Contacts: every company, with its accounts address, accounts email, telephone, VAT number, currency, payment terms and bank details.
Invoices: every shipped dispatch.
Bills: every received delivery with a supplier invoice number.
Credit notes: every completed credit note.
Omono sends a contact again whenever you edit the company or save its accounts address. So the Xero contact always matches Omono. Omono sends invoices, bills and credit notes once. If you change one of them later in Omono, the change is not sent, so correct it in Xero too. If Xero refuses a record, Omono tries it again on every sync until Xero accepts it, so you do not resend a refused record by hand. You do need to open a company and save it again in two cases: Xero accepted it with warnings, or you disconnected and connected again (see below).
Xero does not allow authorised zero-value documents. So when the default status for a document type is Authorised, Omono skips any document of that type with a zero total. The log records the skip. The document is never sent, even if you change the setting later. With Draft or Submitted, zero-total documents are sent as normal.
Omono reads from Xero only what its checks and mapping forms need:
your chart of accounts and tax rates, for the mapping forms and the mapping checks
your currencies and financial year end, for the status checks
whether the Xero user who connected Omono has the Bank account admin permission
a customer's outstanding balance, when you ship a dispatch with Perform Pre-Shipping Credit Limit Check switched on
your rounding account, whenever the sync has bills to send; it is used only if a bill needs a Tax Rounding Adjustment line
The sync repeats the account, tax rate, currency, financial year end and permission checks before each run. It does not import invoices, payments or contacts.
Documents wait for their contact
Omono sends an invoice, bill or credit note only after its company has reached Xero. If the company has not synced yet, the log shows an Error entry saying so. Omono tries the document again next time. If Xero refused the company, the entry says it has errors that must be resolved first. To fix it:
Open the company from the log's View Company link.
Find the company's own entry in the log, "<company> was refused by Xero due to the following errors", and fix what it names in red.
Save the company.
Run the sync again.
The company goes first. Its waiting documents follow in the same run. If Xero accepts a company with warnings, Omono does not send that company again on its own. So its documents stay blocked until you open the company and save it.
Before you connect
Make sure these match between Omono and Xero:
the base currency
every additional currency enabled in Omono
the financial year end (Settings → Company → Accounting Period)
Connecting
Go to Settings → Connect and click the Xero card.
Click Connect to Xero, sign in to Xero and choose the organisation to connect.
You return to Omono. The page shows Xero Connection Status: Connected and the Xero organisation name.
If your account still holds the demo data
If the sign-up demo data is still in your account, Connect to Xero opens Connect To Xero - Demo Data Still Present instead. A sync would send the demo companies, invoices, credit notes and bills to Xero. So do not connect your live Xero organisation while the demo data is there.
To remove the demo data first, click Wipe App Data in the form. It takes you to Settings → App; Wipe App Data is in the Danger Zone at the bottom of that page. Wipe the data, then come back and connect.
To connect a trial or test Xero organisation anyway, tick the box to confirm you understand, then click Connect to Xero in the form. Omono records who ticked the box and when.
If connecting does not work
If you cancel on the Xero site, nothing changes.
Finish the Xero sign-in within 15 minutes of clicking Connect to Xero. If you take longer, you land on a blank page. Go back and click Connect to Xero again. Each click on Connect to Xero, in any tab and by any Admin User, replaces the one before, so only the most recent click can complete.
To switch to a different Xero organisation, click Disconnect from Xero first, then connect again.
If nothing happens when you click Connect to Xero, Xero's sign-in service could not be reached. Wait a minute and try again.
Disconnecting
Click Disconnect from Xero to remove the connection. The button shows only while the setup page can reach Xero; when it cannot (for example while a Xero API Error box shows), Connect to Xero takes its place. Omono also removes itself from the Xero organisation's connected apps. It sets Sync Interval back to Manual / On Demand, so automatic syncing stops. Your mappings and the Xero links on companies and documents are kept.
When you connect again after disconnecting, even to the same Xero organisation, Omono clears the Xero link on every company. Open each company and save it. This sends the company to Xero again, and its documents can then follow. Set the Sync Interval again too. If you connect to a different Xero organisation, Omono creates each company there as a new contact. Documents already sent are not sent again.
Status checks
Every time you open the setup page, Omono contacts Xero and runs the checks. It shows Communicating with Xero, one moment please! while it does so. If Xero refuses the request, a Xero API Error box with a Status Code appears instead. Status code 503 means the Xero API is down for maintenance, so try again shortly. Other messages are explained under Common problems below.
The page lists eight checks, each with a traffic light. Six can turn red. A red light stops the sync until you fix it. These six are:
base currencies match
additional currencies match
financial year end dates match
revenue accounts mapped
expenses accounts mapped
tax rates mapped
The last two checks turn amber instead. An amber light does not stop the sync, but it needs attention:
Contact Bank Account Permission: Xero only lets a user with the Bank account admin permission create or change a contact's bank details. The light is amber when the Xero user who connected Omono does not have this permission. The check shows that person's Omono sign-in email. If they signed in to Xero with a different email, grant the permission to that Xero user. Click How to grant it in Xero for instructions. Until the permission is granted, Omono sends companies with new or changed bank details without those details. Their invoices, bills and credit notes wait. The log shows a warning each sync and an Error line per waiting document. Everything else still syncs. Once the permission is granted, the next sync sends the bank details and the waiting documents. A grey light means the permission could not be checked. Try again later.
Omono Demo Data: amber while the sign-up demo data is still in your account. Click Wipe App Data next to the light to go to Settings → App, then wipe the data in the Danger Zone at the bottom of the page.
When every light is green the page reports that the integration is ready.
Mapping accounts and tax rates
Use the buttons in the action bar. Each opens a form; click the tick at the top to save.
Revenue opens Chart Of Accounts Mapping - Revenue: one row per Omono Sales Analysis code with a Xero Chart Of Account dropdown. It lists » Existing Accounts In Xero. When Xero has no account with the code's name, the dropdown also offers » Create a New Account In Xero. You can create it as Account Type: Sales, Account Type: Revenue or Account Type: Other Income. Choose one of those. When you save, Omono creates the account in Xero, named after the code. The new account takes the first free code between 200 and 299 in your chart of accounts. For a code that is not mapped yet, Omono pre-fills the Xero account of the same name, or else Xero's Sales account; a mapped code shows its saved account.
Expense opens Chart Of Accounts Mapping - Expenses: one row per Purchase Analysis code. Map to a Xero expense or asset account, or create one as Account Type: Direct Cost, Account Type: Expense or Account Type: Overhead.
Tax Rates opens Tax Rates Mapping. Each row shows an Omono rate, for example Standard @ 20%. Each row has a Xero Revenue Tax Rate dropdown and a Xero Expenses Tax Rate dropdown. The revenue dropdown offers only the Xero rates that apply to sales. The expenses dropdown offers only the Xero rates that apply to purchases.
If a mapping button opens nothing, Xero returned no accounts or tax rates. Check the connection and try again.
Keep the mapping complete
The forms list every Sales Analysis code, Purchase Analysis code and tax rate in your organisation, including archived ones and the built-in tax rates. Every row must point at an active Xero account or tax rate. An empty row turns the matching status check red. Every sync then stops with a Critical log entry until you fix it. When you add a code or tax rate in Settings → App, come back and map it before the next sync. If you archive or delete the account or tax rate in Xero, the mapping also breaks. Choose a replacement. If Xero only changes an account's code, Omono picks it up on the next sync and notes it in the log.
Sync settings
Click Settings in the action bar:
Setting | Options |
Sync Interval | Manual / On Demand, Every 15 Minutes, Every Hour, Every 4 Hours, Once Per Day |
Default Invoice Status, Default Bill Status, Default Credit Note Status | Draft, Submitted or Authorised: the status each document is created with in Xero |
Perform Pre-Shipping Credit Limit Check | Off; On - Shipping not allowed if over credit limit; On - Shipping allowed if over credit limit (all users); On - Shipping allowed if over credit limit (admin users only) |
A new integration starts on Manual / On Demand. Nothing is sent until someone clicks Run Sync. To have Omono sync by itself, choose an interval. Omono then syncs at that frequency, from the moment you click the tick.
The default for all three statuses is Authorised. An authorised invoice is created in Xero as approved. It is also marked as sent in Xero. When automatic invoice emails are switched on, Omono emails the invoice when the dispatch ships (see Sending documents by email). Choose Draft or Submitted if you want to check documents in Xero before approving them.
Running and monitoring the sync
Click Run Sync to start a sync now. The form confirms that the sync is starting, or says Xero Sync Already Running. It then closes by itself. The sync runs in the background. Open the log to follow it. While the sign-up demo data is still in your account, Run Sync first shows Demo Data Still Present. Click Cancel to stop, or Run Sync Anyway to send the demo data to Xero. Automatic syncs on an interval run without asking.
Click Sync Log in the action bar, or open Reports → Xero Sync Logs, to see what happened (Admin Users only). Filter by Show (Last Sync Only or All Syncs (last 14 days)), Severity and Types. Auto Refresh Every 10 Seconds (Last Sync Only) is ticked to start with, so the list refreshes itself while a sync runs. Under each message, errors from Xero are listed in red and warnings in orange.
Info: the record was sent, or skipped for an expected reason.
Warning: Omono sent an invoice or bill, but Xero reported warnings. Omono does not send it again. The Bank account admin warning is the exception: it repeats every sync until the permission is granted.
Error: Xero refused the record, or it is waiting for its company. Omono tries it again on the next sync.
Critical (in red): the sync stopped. The document types later in the order are not attempted until the next sync. Fix the problem and run the sync again. The exception is a rate-limit message: after one, Omono runs the sync again by itself.
In Actions, click View Company, View Sales Order, View Purchase Order or View Credit Note to open the record. View Raw API Data, where available, shows exactly what was sent to Xero and what came back. Excel and CSV export the list. Log entries are deleted after 14 days. The report has its own Run Sync button and a Settings button back to the setup page. See Reports.
What Xero receives
Contacts. Xero receives:
the company name
the Omono Account #
the accounts address (as both postal and street address)
the accounts email and telephone
the VAT number
the currency
the Invoice Terms and Bill Terms, as Xero payment terms
The bank sort code and account number go only when they are new or changed. They also go only with the Bank account admin permission. The contact person is named Accounts Manager.
Invoices. Xero receives one sales invoice per shipped dispatch. It is numbered with the Omono invoice number without the INV- prefix, so INV-1042 is invoice 1042 in Xero. The Reference is the order and dispatch number, followed by the Customer Order # when there is one. The dates are the dispatch's invoice date and due date. Each line carries the item details: part number, title, description, tag number, commodity code and country of origin. Each line also carries the quantity and unit price, and the Xero account and tax rate mapped to the line. Foreign-currency invoices carry the order's exchange rate. Each invoice links back to the sales order in Omono.
Bills. Xero receives one bill per received delivery with a supplier invoice number. The Xero invoice number is the supplier invoice number followed by the purchase order and delivery number. The due date comes from the supplier's Bill Terms. Lines carry the item details, quantity and price, and the mapped account and expenses tax rate. If you adjusted the VAT when recording the supplier invoice, Omono adds an extra Tax Rounding Adjustment line. This line posts the difference to Xero's rounding account. Each bill links back to the purchase order.
Credit notes. Each is numbered CN- followed by the Omono credit note number. The Reference # is added to the reference. The credit note is dated the day it was created. Each line carries the item details.
Omono links each company to its Xero contact by a hidden ID, not by name. So renaming a company in either system does not break the link. Xero may already hold a contact with the same name that Omono did not create. If so, Xero refuses the new contact, and the reason appears in the log. Rename or archive the old contact in Xero, or rename the company in Omono. The next sync then retries.
Omono sends prices with the number of decimal places set in Settings → App → Unit Pricing.
Why is an invoice missing from Xero?
Open Reports → Xero Sync Logs, set Show to all syncs and Types to Invoice, and look for the invoice number in the messages (or export to Excel and search there). The usual reasons:
Zero value. A zero-total invoice is skipped when Default Invoice Status is Authorised. The log shows it as skipped.
Customer not synced. The customer must reach Xero as a contact first. See Documents wait for their contact, above.
The sync has not run yet. Click Run Sync to send it now.
Common problems
Message | Cause | Fix |
Base currency not the same / Additional currencies missing / Financial year end must be the same | Omono and Xero differ. | For a missing currency, enable it in Xero. For the financial year end, set Settings → Company → Accounting Period to match Xero. The base currency cannot be changed on either side, so if they differ, connect a Xero organisation with the same base currency, or contact us. |
Issue with the mappings | An analysis code or tax rate is unmapped. | Open the mapping and complete it. |
Xero Access Token Expired | The connection has lapsed. | Contact us through the chat or email [email protected]. |
403 error | Access was revoked in Xero, no sync ran for 60 days, or the Xero trial expired. | Click Connect to Xero again. |
Your organisation has exceeded the Xero per minute (or daily, or concurrent operations) rate limit, retrying automatically in N seconds | Xero limits how many requests an organisation can make. | Nothing. The sync waits and runs again by itself, up to two more times. Do not click Run Sync again. On the setup page, wait a minute and try again. |
<record> was refused by Xero due to the following errors, or (for a whole request) A validation error occurred | Xero rejected the record, for example a contact whose name or Account # another Xero contact already uses, or whose telephone number is too long. The reasons are under the message, or in the raw API data for a whole request. | Fix what the reason names, in Omono or in Xero (for example, restore an archived contact in Xero). The next sync retries it. |
Xero Integration Offline | Omono has paused the integration for maintenance. | Try again later. |
Contact Bank Account Permission Missing, or a log warning that bank details for some contacts were not sent | The Xero user who connected Omono lacks the Bank account admin permission. | Grant it in Xero (see Status checks), or disconnect and connect again as a user who has it. |
Demo Data Still Present | The sign-up demo data is still in your account. | Wipe it in Settings → App before connecting your live Xero organisation. For a trial or test Xero organisation, tick the box on the Connect form, or click Run Sync Anyway on the Run Sync form. |
Credit limit check
When Perform Pre-Shipping Credit Limit Check is switched on, Omono checks the limit each time you move a dispatch to Shipped. This applies on the Workflow board and on the sales order. You see Checking Credit Limit With Xero. The on-stop, proforma and blocking-task rules always come first. The credit check runs after them (see The Workflow board). Omono asks Xero for the customer's outstanding balance. It adds this dispatch's total including VAT. It then compares the result with the company's Credit Limit. Proforma customers are never credit-checked. Once their proforma is paid, the dispatch ships without a Xero check.
Setting | What you see when the customer would go over the limit |
On - Shipping not allowed if over credit limit | Over Credit Limit: "This dispatch cannot be shipped as it will cause the customer to exceed their credit limit." Nobody can ship it until the balance or the limit changes. |
On - Shipping allowed if over credit limit (all users) | "WARNING: This customer will exceed their credit limit if you choose to ship this order" with Yes and No buttons. |
On - Shipping allowed if over credit limit (admin users only) | Admin Users see the warning and can click Yes. Standard Users see Over Credit Limit and "Only admin users can ship this dispatch." |
Within the limit, the normal Good Job! shipping form appears. Sometimes Omono cannot get an answer from Xero. Then the form warns that it could not check the limit, and asks you to check with the account manager. You can still click Yes. This happens:
when Xero is unavailable
when the customer has not yet reached Xero as a contact
when the company has no Credit Limit stored at all (a blank Credit Limit in the company form is saved as 0, which counts as a limit)
A Credit Limit of 0 fails the check on every shipment. Before you rely on the check, give every customer a limit and make sure they have synced.
Signing up from the Xero App Store
You can register for Omono from its listing in the Xero App Store. Omono takes your name and email from your Xero sign-in and your company name, country, base currency and telephone from your Xero organisation; the Register form then only asks you to agree to the Terms of Service and Privacy Policy. See Registering and signing in. Signing up this way does not connect your new organisation to Xero. After you sign in, go to Settings → Connect and follow the steps above. The organisation may start with the sign-up demo data. Wipe it before you enter real data.