Xero Accounting Sync for OpenCart

Overview

Xero Accounting Sync books the orders of your OpenCart shop in your own Xero organisation. A customer places an order, the order reaches the status you chose, and a few minutes later the contact, the sales invoice and the payment are in Xero, with your account codes and tax types. A refund or a product return becomes a credit note, paid back from the bank account or applied to the open invoice.

What it does

• Connection. You connect your own Xero app (OAuth 2.0 authorization code flow with the granular accounting scopes) and choose the organisation. Test mode with the Xero Demo Company and live mode are kept side by side. Credentials and tokens are stored encrypted, the refresh token is renewed by the extension (it rotates on every use) and kept alive weekly.
• Contacts. Found by e-mail address or created once, updated only when the customer data changed. Guests are handled.
• Sales invoices. One per order with the invoice number prefix you set (for example WEB-1042), product lines (with options), shipping, fees and discounts, your account codes, the Xero tax type and the tax amount of every line, in the currency of the order. Approved or draft, due days, optional Xero items from product SKUs.
• Payments. Recorded against the invoice in the bank account mapped to the payment method of the order.
• Credit notes. For a refunded order (whole order) and for a product return (the returned product and quantity), paid back from the bank account when the invoice was paid, applied to the invoice when it is still open.
• Mapping page. Sales, shipping and discount accounts, a bank account per payment method, a Xero tax type per OpenCart tax rate. Account and tax lists are loaded from your Xero; suggested tax types for organisations in the United Kingdom, Australia and New Zealand.
• Reliable. Every create call carries an idempotency key, so a retried job never books a document twice. Rate limits (429) wait the time Xero asks for. A job queue with retries, a sync list with Xero IDs, a Jobs page and a filtered log with CSV export. Secrets never reach the log.
• Events and cron only, no OCMOD, no core edits. OpenCart 4, tested on 4.1.0.4.

Limits to know

• You need your own Xero organisation and a Xero app (client ID and secret) created in the Xero developer portal. Xero decides which plans may use the API and its limits (60 calls a minute, 5,000 a day per organisation).
• One OpenCart store and one Xero organisation. Orders are booked in the currency of the order; the currency must be enabled in Xero (Xero multi-currency).
• Order level discounts (coupons, reward points) are booked as one discount line; the tax of the order comes from the order's tax totals. A product return is credited at the price the product was ordered at, without a share of an order level discount. Fees (handling, low order fee) are booked without tax.
• Orders whose lines do not add up to the order total (a custom extension changed the total) are refused with the reason and not sent.
• Changes made in Xero are not read back. Approved invoices are left alone by the shop.
• The extension was tested against a stand-in of the Xero API built from Xero's published OpenAPI files and scope table, not against a live Xero organisation. Not affiliated with Xero.

Xero is a trademark of Xero Limited. This extension is not made, endorsed or certified by Xero.

Installation

Requires OpenCart 4.1 (tested on 4.1.0.4), PHP 7.4 or newer with the cURL and OpenSSL extensions, and a store reachable over HTTPS (Xero sends the browser back to your shop).

1. In the admin go to Extensions > Installer, upload kv_xero.ocmod.zip and click Install.
2. Extensions > Extensions, choose "Modules", find "Xero Accounting Sync" and click Install (the green button).
3. Click Edit. Switch the extension on and, if you have one, enter your Kavio Labs license key. Without a key the extension works for 14 days.
4. The pages are under Sales > Xero: Xero sync, Connection, Mapping, Log, Jobs.
5. Cron. The install registers an hourly entry in the OpenCart cron, which needs the standard OpenCart cron line on your server (shown on the settings page). For a faster sync call the secret web address from the settings page every few minutes with your host cron.

Uninstall removes the stored credentials, the sync map, the job queue and the log. What was booked in Xero stays in Xero.

What you need from Xero

1. In the Xero developer portal create an app of the type "Web app" (OAuth 2.0 authorization code flow).
2. Add the Redirect URI shown on the Connection page, exactly as written.
3. Copy the client ID and create a client secret. Enter both on the Connection page (test or live credentials), save, then press "Connect to Xero" and approve the access for your organisation. Start with the Xero Demo Company in test mode.

Configuration

Settings (Extensions > Modules > Xero Accounting Sync > Edit)

Connection

Client ID and secret of your Xero app for test and for live mode; the mode switch picks one. After "Connect to Xero" the page shows the access that was asked for (offline_access accounting.invoices accounting.payments accounting.contacts accounting.settings.read) and the organisation the books are written to. With several organisations choose one and press "Use this organisation".

Mapping

Press "Load accounts and tax types from Xero" and "Fill the tax types suggested for my country", then check:

• Sales, shipping and discount account codes.
• A bank account code for each payment method of your store, and a default bank account for the others. The account must be a bank account or allow payments in Xero.
• The Xero tax type for each OpenCart tax rate (for example VAT 20% to OUTPUT2), a standard tax type, a tax type for lines without tax and one for shipping.

Usage

Daily work

Nothing to do. When an order reaches the chosen status the extension queues a job; the cron run books it. The Xero sync page lists every contact, invoice, payment and credit note with its number, currency, amount and Xero ID, and links to the order.

• Sync order now. Type an order ID to queue it again (for example after fixing the mapping). Nothing is booked twice: an unchanged order is skipped, a draft invoice is updated, an approved invoice is left alone.
• Queue past orders. Queues the orders in the trigger statuses since the sync date that Xero does not have yet.

Refunds and returns

Set an order to the refund status: a credit note with the lines of the invoice is created and paid back from the bank account (paid order) or applied to the invoice (unpaid order). For a product return give the return the chosen return status (Sales > Returns): a credit note for the returned product and quantity is created the same way.

Jobs and log

The Jobs page shows the queue: queued, waiting to retry, done, gave up. A failed job is retried after 5 minutes, then 15 minutes, 1, 3 and 12 hours; a rate limit waits the time Xero asks for; a lost authorization waits for you to connect again. "Retry" and "Remove" are on every row. The Log page has filters and a CSV export; secrets and tokens never appear in it.

Xero is a trademark of Xero Limited. This extension is not made, endorsed or certified by Xero.

Developer notes

Identity

Events and cron

Cron: extension/kv_xero/accounting/xero.cron (OpenCart cron, or the secret web address). The Xero redirect URI is the storefront route extension/kv_xero/accounting/xero.callback; its state is kept in the database as a SHA-256 hash, single use, 15 minutes.

Structure

Client\BaseClient (HTTP, Retry-After, error mapping), Client\Api (OAuth and Accounting API), Sync (contact, invoice, payment, credit note, return), Store (reads an OpenCart order), Accounts and Secret (credentials sealed with AES-256-GCM, token refresh under a database lock), Queue, Jobs, Log, Connect (authorization flow).

Idempotency keys: kv-inv-<order>-<hash>, kv-pay-<order>, kv-cn-<order>, kv-rf-<order>, kv-al-<order>, kv-cn-rt-<return>, kv-rf-rt-<return>, kv-al-rt-<return>.

Tests

php tests/unit.php (PHP 8.1 and 8.3), node tests/mock-server/server.js 11923 (stand-in of the Xero identity service and Accounting API; the base URL is the setting module_kv_xero_base_url, development only) and node tests/e2e.js (browser test on a dev store).

API conformance (official Xero documentation)

Checked on 2026-11-06 against developer.xero.com. The stand-in carries the official scope list and the resource-to-scope table, refuses the deprecated broad scopes with invalid_scope and answers 403 when a token lacks the scope that covers a resource.

Trademark: Xero is a trademark of Xero Limited. This extension is not made, endorsed or certified by Xero.

FAQ

Does it use OCMOD?

No. Events and cron.

Does it work with OpenCart 3?

No, OpenCart 4 only.

Do I need a Xero app?

Yes, your own. Your order data goes from your shop straight to your Xero organisation.

Which Xero plans work?

The ones that Xero allows to use its API. Check the current rules and limits in the Xero developer documentation.

Why is a payment not recorded?

Most often no bank account is mapped for the payment method and there is no default bank account. The Jobs page shows the message. Fix the mapping and press Retry.

Why was an order refused ("lines add up to ... but the order total is ...")?

Something changed the order total without a matching line, for example a custom total extension. Nothing is sent so that Xero never gets a wrong invoice; correct the order or book it by hand in Xero.

The authorization is gone. Xero refresh tokens expire after 60 days without use or when the user revokes the app. Press "Connect again" on the Connection page; jobs wait and run afterwards.

Existing connections after an update?

If an update changes the requested access, press "Connect again" once.

Multi-currency?

Invoices are in the currency of the order; the currency must be enabled in your Xero organisation.

Is it certified by Xero?

No. Xero is a trademark of Xero Limited; this extension is not made, endorsed or certified by Xero.