Xero Odoo Connector User Guide: Setup, Sync and Webhooks

The Xero Odoo Connector (technical name ki_xero_connector) links Odoo with Xero Cloud Accounting. It syncs invoices, bills, payments, contacts, products and orders in both directions. This guide covers installation, setup, each main feature, and the limits you should know before you start.

You can buy and install it from the store page: Xero Odoo Connector on the KalvyAI Store.

What the connector is for

If your team runs sales, purchasing and stock in Odoo but your accountant works in Xero, someone usually re-keys invoices and contacts between the two. That is slow, and it creates duplicates and mismatched tax amounts.

The connector removes that manual step. It is a single, self-contained module that plugs into standard Odoo Invoicing, Sales, Purchase and Inventory. You do not need to buy a separate base module.

What it syncs:

• Customer invoices (ACCREC) and vendor bills (ACCPAY)
• Credit notes and refunds
• Payments, with line-level taxes, accounts and currency tracking
• Customers and vendors
• Products
• Orders

Who it helps

• Business owners who want Odoo and Xero to show the same numbers without double entry.
• Accountants and bookkeepers who work in Xero and need clean, correctly taxed documents from Odoo.
• ERP admins who need a connection they can monitor, retry and audit.
• Groups with several entities that run multiple Xero organisations against separate Odoo companies.

Requirements

Check these before you install:

• Odoo 19.0 or 20.0, Community or Enterprise, on Odoo.sh or a self-hosted server
• Standard Odoo modules: Invoicing (account), Sales (sale_management), Purchase (purchase) and Inventory (stock)
• An active Xero subscription (Starter, Standard or Premium)
• A free Xero Developer App created on developer.xero.com (you need its Client ID and Client Secret)
• A public HTTPS address if you want real-time webhooks. Manual and scheduled syncs work without one.

Odoo Online (SaaS) is not supported, because it does not allow custom modules.

Installation and setup

Step 1: Install the module

1. Get the module from the store page.
2. Add it to your addons path. On Odoo.sh, commit it to your repository branch.
3. Update the apps list and install Xero Odoo Connector. The required dependencies (Invoicing, Sales, Purchase, Inventory) are installed automatically.

On a self-hosted server you can also install from the command line:

./odoo-bin -d your_database --addons-path=/path/to/addons -i ki_xero_connector

Step 2: Create a Xero app and connect with OAuth 2.0

1. Log in at developer.xero.com and create a new Web App.
2. Set the redirect URI to the value shown in Odoo: [CHECK: where the connector displays the OAuth redirect URI, and its format].
3. Copy the Client ID and generate a Client Secret.
4. In Odoo, open the connector configuration: [CHECK: menu path to the Xero connector configuration / instance form].
5. Create a new instance, choose the Odoo company it belongs to, and paste the Client ID and Client Secret.
6. Click Connect to Xero, log in to Xero, and approve access for the organisation you want to link.

Authentication uses OAuth 2.0 with automatic token refresh, so you should not need to reconnect during normal use.

Step 3: Map taxes and accounts

Do this before you sync any historical invoices. Unmapped taxes and accounts are the most common cause of failed or wrong documents.

1. Open the instance and run the 1-Click Smart Tax Auto-Discovery wizard. [CHECK: button location on the instance form]
2. The wizard reads Xero's tax rates, computes the effective rate of each, and suggests the matching Odoo sales and purchase taxes.
3. Review the suggested pairs. Correct any that look wrong.
4. Save. All mapping pairs are stored in one step.
5. Run the Account Auto-Mapping wizard to link Xero ledger codes to Odoo accounts, then review and save the result.

Step 4: Choose sync directions and enable webhooks

1. On the instance, set the sync direction for each entity type. [CHECK: available direction options per entity, e.g. import only / export only / both]
2. Set your accounting defaults and conflict policy. [CHECK: list of conflict policy options and what each does]
3. Copy the webhook URL from the instance. [CHECK: where the webhook URL is shown in Odoo]
4. In your app on developer.xero.com, open the webhooks section and paste the URL.
5. Enter the Xero webhook key into Odoo so signatures can be verified. [CHECK: field name and location for the Xero webhook signing key]

Webhooks need a publicly reachable HTTPS domain. If your server is internal, skip this step and use scheduled or manual syncs.

Step 5: Decide on scheduled syncs

Scheduled sync jobs are installed inactive. This is deliberate, so nothing runs in the background until you are ready.

1. Enable developer mode in Odoo.
2. Go to Settings > Technical > Scheduled Actions.
3. Find the Xero sync jobs. [CHECK: exact names of the connector's scheduled actions]
4. Set the interval you want and activate them.

Using the main features

Syncing contacts without duplicates

When a contact comes from Xero, the connector checks for an existing Odoo partner before creating anything. It matches in tiers:

1. VAT / tax number
2. Normalized email address
3. Cleaned phone number
4. Contact name

If a match is found, the records are linked. If not, a new partner is created. Example: a Xero contact with email Billing@Acme.com ` links to the Odoo partner with `billing@acme.com, because the email is normalized before comparison.

To sync contacts, run a contact import or export from the Quick Sync Hub, or push a single contact from its form (see below).

Syncing invoices, bills, credit notes and payments

Customer invoices go to Xero as ACCREC documents and vendor bills as ACCPAY. Credit notes and refunds are supported. Lines carry their taxes, accounts and currency.

Payments work in both directions:

• A payment recorded in Odoo is exported to Xero and applied to the mapped invoice.
• A payment recorded in Xero reconciles the matching Odoo invoice.

One rule to remember: once an invoice or bill is Paid in Xero, it cannot be edited there. Make corrections with a credit note or a payment adjustment instead of editing the original document.

Quick Sync Hub and push buttons

Use the Quick Sync Hub for on-demand, per-entity imports and exports.

1. Open the Quick Sync Hub. [CHECK: menu path to the Quick Sync Hub]
2. Pick the instance (Xero organisation) to work with.
3. Choose the entity, for example contacts, products or invoices.
4. Run the import or export.
5. Check the Diagnostics log for any failures.

For single records, open the invoice, bill or contact in Odoo and use the push action button on the form. [CHECK: exact button label on invoice, bill and contact forms] This is useful when one document needs to reach Xero now, without waiting for a scheduled run.

Real-time webhooks

With webhooks enabled, Xero notifies Odoo when contacts or invoices change, and the update arrives in seconds instead of waiting for the next scheduled sync. Each incoming request is checked with an HMAC-SHA256 signature, so Odoo only accepts payloads that really come from Xero.

Webhooks cover contact and invoice updates from Xero. Keep scheduled syncs for everything else you want automated.

Diagnostics and Self-Heal & Retry

Every sync writes a structured log entry. When a Xero API call fails, the log shows:

• A plain-English summary of what went wrong
• A hint on how to fix it
• A Self-Heal & Retry button

Typical workflow:

1. Open the Diagnostics log. [CHECK: menu path to the Diagnostics / sync log]
2. Filter for failed entries.
3. Read the hint. For example, it may point to a missing tax mapping.
4. Fix the cause, such as adding the mapping.
5. Click Self-Heal & Retry.

Multiple Xero organisations and companies

Each Xero organisation gets its own instance, linked to one Odoo company. Every instance has its own credentials, accounting defaults, conflict policy and audit log.

To add another organisation, repeat Steps 2 to 4 with a new instance and select the right Odoo company.

Tips

• Map first, sync second. Finish tax and account mapping before importing historical invoices.
• Start with contacts and products. Invoices reference both, so syncing them first avoids failed lines.
• Test with a small batch. Push a handful of invoices from their forms and check them in Xero before running bulk syncs.
• Watch the rate limits. Xero allows about 60 calls per minute and 5,000 calls per day per tenant. Spread large historical imports over time.
• Turn on crons last. Once manual syncs look right, activate the scheduled actions.
• Review the log weekly. A quick look at failed entries keeps small issues from piling up.

Limitations

• Odoo Online (SaaS) is not supported. Use Odoo.sh or a self-hosted server.
• Real-time webhooks need a public HTTPS domain. Local or internal servers can use scheduled syncs or the Quick Sync Hub.
• Xero's API rate limits apply (for example 60 calls/minute and 5,000 calls/day per tenant).
• Scheduled sync jobs are inactive after installation until you turn them on.
• Invoices and bills marked Paid in Xero cannot be edited directly. Use payments or credit notes.
• Taxes and the chart of accounts should be mapped before historical invoice syncs.

FAQ

Which Odoo editions and versions are supported? Odoo 19.0 and 20.0, Community and Enterprise, on Odoo.sh or self-hosted servers.

Do I need to buy a separate base module? No. The connector is standalone and only needs the standard Odoo apps Invoicing, Sales, Purchase and Stock.

Will importing from Xero create duplicate contacts? No. It checks VAT number, normalized email, phone and name before linking to an existing Odoo partner.

Can I connect multiple Xero organisations? Yes. Create one instance per Xero organisation, each linked to a specific Odoo company.

What happens if an API call fails during sync? The error is recorded in the Diagnostics log with a plain-English fix hint and a Self-Heal & Retry button.

How does payment allocation work? Payments recorded in Odoo are exported to Xero and applied to the mapped invoice. Payments recorded in Xero reconcile the Odoo invoice.

Do I need a public URL? Only for real-time webhooks. Manual and scheduled syncs work without one.

How KalvyAI can help

We build and connect Odoo, ERPNext and Shopify systems, and we support the Xero Odoo Connector. If you want help with installation, tax and account mapping, migrating historical data from Xero, or setting up webhooks on Odoo.sh or your own server, we can do it with you. We also add AI agents that work inside Odoo with human approvals, budgets and an audit trail, for example to review sync failures or prepare invoices for approval.

Get the module on the store page, or contact us to talk through your setup.