WooCommerce Xero - WordPress Plugin

A Practical Guide to Setting Up WooCommerce Xero for Your Store and Accounting Workflow

WooCommerce Xero is not for building your storefront or managing the cart. Its job starts after the order is placed: the plugin sends sales data from WooCommerce to Xero, creates an invoice, links the payment to that invoice, and leaves a trace in the order so you can verify the result. In this guide, we will cover not just installation, but also the logic behind account codes, taxes, payments, product codes, resending orders, and troubleshooting errors.

This guide is written for store owners, WooCommerce administrators, accountants, and developers helping with the integration. It does not cover subscription purchases or licensing workarounds. We assume the plugin is already available and that your goal is to connect it to a live store safely, test it with a single order, and understand where automation begins and where it stops.

The key point is simple: you should never enable this kind of integration blindly. Even if the Xero connection works, problems usually show up later - in account codes, tax rates, order statuses, payment accounts, product SKUs, and invoices that have already been paid, which Xero will not let you edit through the API. That is why a solid WooCommerce Xero rollout should be treated like a small project: prepare, connect, configure, run a test order, verify the result in both systems, and only then switch it on for regular use.

What Problem This Store-to-Xero Integration Actually Solves

If your store processes orders regularly, manually transferring sales into accounting quickly becomes a weak point. Someone has to copy the customer name, address, line items, discount, shipping, tax, total, and payment details. At a small scale, that may seem manageable, but in practice manual entry leads to delays, mismatches, and messy edge cases: the WooCommerce order is already paid, but there is still no invoice in Xero; the customer received a discount, but it was recorded differently in accounting; shipping was posted to the wrong account; the tax rate has a different name in each system.

WooCommerce Xero automates exactly that part of the workflow. According to the official documentation, the plugin creates Xero invoices for WooCommerce sales and sends product, shipping, discount, and tax data. When payment is completed, the linked invoice can also be marked as paid in Xero if your payment settings allow it. WooCommerce order notes then show the result of the transfer, so the administrator can see whether an invoice was created, whether the payment was sent, and which identifier the object received in Xero.

That said, the plugin does not turn WooCommerce and Xero into a single shared database. It is important to understand that from the start. It is not a full two-way inventory sync, it does not automatically route different payment gateways to different Xero bank accounts, and it does not fix a weak accounting model. It sends sales according to the rules you define in the settings, and the quality of the result depends on how cleanly your account codes, tax rates, SKUs, and order status workflow line up.

What Gets Sent from WooCommerce to a Xero Invoice

In the default setup, Xero receives customer data, address fields, the order date and number, product lines, quantities, prices, shipping, discounts, tax, and the final total. If product code transfer is enabled, the WooCommerce SKU is sent as the item code in Xero. That is useful because the accountant can see not just total revenue, but the actual makeup of the sale. The tradeoff is that it raises the bar for data quality: if the SKU does not match the Item Code in Xero, the error will show up as soon as the invoice is created.

The plugin creates invoices in a status that Xero accepts for further processing. Woo documentation states that the invoice status is always sent as AUTHORIZED, while the tax type depends on your WooCommerce settings and how they are matched to Xero. That makes tax configuration one of the central stages of the setup, not a minor detail.

Where Automation Saves Time and Where You Still Need Manual Review

Automation works best for repeatable orders: a standard product sale, a clear tax rate, one payment, regular shipping, and a familiar discount. In that kind of scenario, the administrator gets a Xero invoice and a WooCommerce order note without any manual copying.

Manual review is still necessary when the accounting logic is less straightforward: multiple payment gateways, multiple currencies, zero tax rates, shipping tracked separately as income or expense, gift certificates, prepayments, refunds, older orders, edited invoices, and products that use different account codes. The plugin gives you tools for some of these cases, but it does not remove the need for an accounting decision.

Practical rule of thumb: start with a standard order and one clear payment scenario. Once that reliably creates both the invoice and the payment, move on to discounts, shipping, zero-tax setups, SKU matching, and older orders.

Who WooCommerce Xero Is a Good Fit For and When Another Approach Makes More Sense

WooCommerce Xero is especially useful for stores that already do their accounting in Xero and want new orders to appear there without manual entry. That can include stores selling physical products, digital products, services, or a mixed catalog, as long as the accounting model is simple enough and all sales can be processed through one consistent rule set.

The plugin is a good fit if your accountant needs separate invoices for individual orders instead of just a daily sales summary. It is also helpful when the store owner wants a direct link between the WooCommerce order and the Xero invoice right inside the order notes. That connection makes reconciliation easier: you can open the order, see the invoice transfer message, jump to the accounting record, and quickly spot where the mismatch happened.

Strong Use Cases for This Plugin

• The store creates a separate Xero invoice for each WooCommerce order and wants to eliminate manual entry.
• Orders usually flow through one primary payment account in Xero.
• Tax rates in WooCommerce can be aligned with the same names and values used in Xero.
• The administrator is willing to test the transfer on a single order first and review order notes when errors appear.
• The store uses clear SKUs that can be matched to Item Codes in Xero if you want Xero inventory to decrease on sale.

When the Plugin May Be Too Basic

There are scenarios where the standard integration may not cover everything you need. Reviews on the WooCommerce page have specifically called out limitations around payment accounts and contacts. The documentation confirms one key detail: the integration supports only one Payment Account, so all WooCommerce payments, regardless of gateway, are posted in Xero under the single account defined in the settings. If you need Stripe, PayPal, bank transfer, and invoice payments to be routed automatically into separate Xero bank accounts, the standard setup may not be enough.

Contacts are another sensitive area. The documentation describes the Use customer email in contact name option, which helps prevent data from being overwritten when Xero already contains a contact with a similar name or company. But if your store has a very large number of one-time buyers, you should discuss in advance with your accountant how contacts should be handled, how personal data should be stored, and whether the accounting database might end up overloaded with thousands of records.

If you need two-way inventory sync, separate export of payment gateway fees as expenses, flexible payment routing by payment method, advanced field mapping, or controlled bulk migration of old orders, it is worth comparing WooCommerce Xero with more specialized services. That does not mean the plugin is weak. It means it has a clear scope: automatically sending WooCommerce orders to Xero based on WooCommerce rules, not acting as a full accounting platform.

What to Check Before Installing It on a Live Store

Preparation is not just a formality. An accounting integration error may not show up on the product page - it may show up in your financial records, where fixing it takes much more time. Before installing the plugin, check technical compatibility, access permissions, your testing strategy, and the accounting model itself.

Technical Requirements and Access

The WooCommerce product page lists the current version requirements for WordPress, WooCommerce, and PHP, and the documentation also mentions cURL, cURL SSL, and a valid SSL certificate. Do not rely on old blog posts that quote outdated minimum versions. Before installation, check the current requirements on the product page and compare them against your site.

To connect the integration, you will need WordPress admin access with permission to install plugins, plus access to the Xero Developer Portal under an account that can create an app and connect the correct organization. You will also need access to the Chart of Accounts in Xero, because invoices and payments require valid account codes.

A Safe Testing Plan

It is better not to connect the integration directly to your live order flow. Prepare a test product with a small price, a simple shipping method, a clear tax rate, and a separate test order. If the store is already taking real orders, it is usually safer to test the plugin on a site copy or during a quiet period when you can spot problems quickly.

Your validation should answer five questions:

1. After saving the Client ID and Client Secret, does the Sign in with Xero button become active in WooCommerce Xero settings?
2. After authorization, does the connection status return to OK?
3. Is a Xero invoice created after the selected order event?
4. Is the payment sent to Xero at the right moment?
5. Are WooCommerce Order Notes updated with the Xero number or error message?

Your Accounting Model Before Installation

The most common mistake is installing the plugin before your account codes are clearly defined. In Xero, you should already have accounts prepared for sales, shipping, fees, payments, and rounding, if those exist in your workflow. For the Payment Account, make sure it can actually be used to record payments. Xero specifically documents the Enable payments to this account setting, without which payments may fail to export.

If your store uses taxes, make sure names and rates can be mapped properly. WooCommerce Xero can append the rate percentage to a tax rate name during matching, but if WooCommerce says one thing and Xero expects another, the invoice may fail or be sent with the wrong tax type. For zero rates, plan a separate approach: Woo documentation describes the Match Zero Value Tax Rates setting and the related product requirements so a zero rate is sent intentionally instead of disappearing from the invoice line.

Installation, the Xero App, and the First Connection

After installing the plugin in WordPress, the main work happens between two interfaces: WooCommerce Xero settings and the Xero Developer Portal. The purpose of this step is to create a Xero app, obtain the Client ID and Client Secret, enter the Redirect URI, and grant WooCommerce access to the correct Xero organization.

Installing the Plugin in WordPress

The standard path looks like this: in the admin panel, open Plugins, then Add New, choose ZIP upload, install the plugin, and click Activate. After activation, go to the Xero settings in WooCommerce. The documentation describes the path as WooCommerce > Xero or the WooCommerce Xero settings page. On that screen, you will see the Redirect URI that must be copied into the Xero Developer Portal.

If the store uses admin caching, a custom wp-admin path, or a security plugin, do not change too many parameters at once. First make sure the settings page loads correctly and that you can save the basic fields. Only then should you layer on additional security measures. OAuth connections are sensitive to exact URL matching.

Creating an App in the Xero Developer Portal

In the Xero Developer Portal, open the apps section and create a new app. Woo documentation states that the integration type must be Web app, and the Redirect URI should be taken from your WooCommerce Xero settings. Choose a simple app name without symbols, because the documentation warns that symbols in the name can interfere with the connection.

Next, copy the Client ID into the plugin settings, generate the Client Secret, and save it in WooCommerce Xero immediately. The secret is shown only once. If you lose it before saving, it is better to generate a new one than to guess the old value.

Choosing the Correct OAuth Scopes Option

The WooCommerce Xero connection settings ask whether the Xero app was created before a specific date when API scopes changed. This is not just a decorative option. Xero moved newer apps to more granular permissions, and the wrong choice can cause the error unauthorized_client - Invalid scope for client. If the app was created after the date mentioned in the setting, choose the option for a new app. If it is an older app, choose the legacy option. If you get the error, disconnect the integration, save the correct choice, and authorize again.

Once the Client ID, Client Secret, and scopes option are saved, the Sign in with Xero button should become active. Click it, sign in to Xero, choose the organization, and confirm access. If you have multiple organizations, select the live organization rather than the demo company. Woo documentation specifically notes that the Demo Company may not be suitable for this type of connection.

Post-connection check: return to the WooCommerce Xero settings and confirm that the connection status shows OK. Do not move on to sending orders until that status is confirmed.

Configuring Account Codes, Taxes, Payments, and Product SKUs

This section matters more than the installation itself. OAuth only opens the channel between the systems. After that, you still need to tell the plugin which Xero accounts to use for sales, shipping, fees, payments, rounding, and taxes. If you skip this step, the order may fail to send, go to the wrong place, or require manual cleanup inside Xero.

Default Account Codes

In Xero, open Accounting, then Chart of Accounts or the advanced accounting settings section. Find the account codes that correspond to sales, shipping, fees, payments, and rounding. In WooCommerce Xero, fill in every required field. Woo documentation explicitly states that all Account Code fields must be completed for invoices to be sent.

Do not copy account codes from someone else's article. The account structure in Xero depends on your country, your organization template, and how your accountant runs the books. One store may treat shipping as revenue, another as an expense or a pass-through reimbursement. That is why the Treat Shipping As and Treat Fees As settings must match the account type in Xero. If the account type does not line up, Xero may return an error about an incompatible TaxType and account code.

Send Invoices and the Timing of Invoice Creation

The Send Invoices setting controls when WooCommerce Xero creates or updates an invoice. The documentation describes several modes: manually through order actions, on order creation, after payment completion, or when the order moves to Completed. For most stores, it is safer to start with Payment completion, because the invoice is created after payment is confirmed rather than at the moment the customer merely begins checkout.

On creation is not always the right choice. It may create an invoice before it is clear whether the order will actually be paid. Manual works well during testing and for occasional B2B orders where the accountant wants to review the order before sending it. On order completion fits stores where Completed means the order is fully ready for accounting, but it can delay the invoice if orders stay in processing for a long time.

Send Payments and the Single Payment Account Limitation

The Send Payments setting determines when the Xero invoice will be marked as paid. Two limitations matter here. First, once a payment is applied and the invoice reaches the PAID status, Xero no longer allows that invoice to be changed through the API. If the order may still change, do not send the payment too early. Second, WooCommerce Xero uses one Payment Account. If the store accepts payments through multiple gateways and your accountant wants them tracked in separate accounts, you will need to solve that outside the standard plugin settings or choose another tool.

For the Payment Account, verify in Xero that the account exists, has the correct reference code, and allows payment posting. If invoices are being created but payments are not being sent, start there. Do not change OAuth, tax rates, and order statuses all at once - it becomes much harder to isolate the real cause.

Taxes, Zero Rates, and Exact Name Matching

Taxes require precision. WooCommerce and Xero need to speak the same language: the rate name, percentage, and purpose should all match. Woo documentation describes the Append Rate Percentage When Matching setting, which adds the percentage to the tax rate name during matching. If the rate in WooCommerce is called VAT but Xero expects VAT (20.00%), that option may help. If you disable it, the names must match exactly.

For tax-free products, do not rely on accidental behavior. By default, WooCommerce may not send tax on the line item if the rate is zero or the product is non-taxable. WooCommerce Xero includes the Match Zero Value Tax Rates setting, which helps explicitly map a zero rate. But to make that work, you need to create the matching zero rate in WooCommerce, configure the product as taxable with the correct tax class, and verify how WooCommerce calculates the tax.

Send Inventory Items and the Limits of Stock Tracking

The Send Inventory Items option sends the WooCommerce SKU as the Item Code in Xero. That can reduce the quantity of an existing inventory item in Xero when a sale occurs. But the documentation stresses an important limitation: this is not a full inventory synchronization system between WooCommerce and Xero. The plugin will not automatically reconcile stock when it is manually adjusted in one of the systems.

Enable this mode only if SKUs in WooCommerce consistently match Item Codes in Xero and the accountant genuinely tracks inventory in Xero. If the store has duplicate legacy SKUs, variations without SKUs, or products that do not exist in Xero as items, clean up your product data first. The error Item code is not valid almost always points not to a "broken plugin," but to a mismatch between the SKU and the Item Code.

How a WooCommerce Order Becomes a Xero Invoice

Understanding the mechanics makes troubleshooting much easier. The plugin does not simply "sync the order." It takes a set of order fields, maps them against your settings, creates or updates an invoice, and then sends the payment when the right trigger occurs. Each step has its own conditions and common failure points.

The Data Flow

First, an order appears in WooCommerce. Based on the Send Invoices setting, the plugin decides whether it is time to create an invoice. It pulls the customer contact details, order lines, shipping, discounts, tax, and total. If inventory items are enabled, the SKU becomes the Item Code. The data is then sent to Xero using the selected account codes and tax mappings.

If Xero accepts the invoice, WooCommerce adds a note to the order. That note is the administrator's main checkpoint. It confirms that the invoice was created and helps you locate it in Xero. If the invoice is not created, the note will contain the error. So when launching the integration, do not look only at the order list. Open the actual order and read the Order Notes.

What Happens to the Payment

The payment is sent separately from the invoice. If an automatic mode is selected in Send Payments, the plugin applies the payment to the linked invoice when WooCommerce considers the payment complete or when the order reaches the required status. After that, the invoice in Xero becomes paid. From that point on, it can no longer be changed through the API, so any corrections must be handled manually in Xero or by creating a new accounting entry that reflects the correct result.

This behavior is especially important for stores where orders often change. If staff regularly add line items after payment, edit shipping, adjust discounts, or combine orders, automatic payment export may happen too early. In those stores, it makes sense to test manual mode or send the payment only at a later order status.

Discounts and Coupons

The WooCommerce Xero documentation shows several discount scenarios: percentage discounts, fixed cart discounts, fixed product discounts, and multiple coupons. In Xero, the discount amount appears across the invoice lines. The documentation also notes that the discount amount is transferred, not the coupon code itself. If your accountant needs the actual coupon code inside Xero, check whether you have a separate process for that requirement.

For standard reconciliation, the discount amount is usually enough. For marketing analysis by promo code, WooCommerce reports or separate analytics tools are a better fit, because Xero in this workflow does not become a full coupon CRM.

Practical Scenario: Test Order, Invoice, and Payment

Below is a test scenario worth running before you enable the integration for regular order flow. It does not depend on a specific payment gateway and helps you validate the main settings with minimal risk.

Test Goal

The goal is to confirm that WooCommerce Xero creates a Xero invoice from a WooCommerce order, correctly sends the product, shipping, discount, and tax data, and then applies the payment at the expected time. You also need to verify that the WooCommerce order keeps clear and readable notes.

Preparation

• Create or select a test product with a clear SKU if you plan to validate Item Code behavior.
• Set up a simple flat shipping method if shipping exists in the real store.
• Create one coupon with a small discount if discounts are used regularly.
• Check the tax rate in WooCommerce and the matching tax rate in Xero.
• Select the Send Invoices and Send Payments modes you plan to use in production.
• Enable Debug during testing so that if something fails, you can quickly find the log in WooCommerce > Status > Logs.

Validation Steps

1. Place a test order as a normal customer, or create the order manually in the admin panel if your workflow allows that.
2. Move the order to the status selected in Send Invoices. If you are using manual mode, open the order, choose the Send Invoice to Xero action, and apply it.
3. Open Order Notes and check whether you see an invoice creation message or an error.
4. Go to Xero, open the invoices section, and locate the invoice by number, customer, or amount.
5. Compare the invoice lines: product, quantity, price, discount, shipping, tax, and total.
6. If payment export is enabled, check whether the invoice status in Xero changes after payment completion or after the order reaches the required status.

Expected Result

In the ideal case, Xero shows an invoice with the same financial lines as WooCommerce. The WooCommerce order contains a note confirming successful invoice creation and, if payment was sent, a separate payment note. If something does not match, do not roll the integration out to all orders yet. Fix one discrepancy, then rerun the test using a new order or a prefix that will not conflict with an invoice that already exists.

A Caveat About Paid and Edited Invoices

If the invoice has already been marked as paid in Xero, the plugin will not be able to edit it freely through the API. That is a normal Xero limitation, not necessarily a WordPress error. So test changes using a new order rather than trying to overwrite the same paid invoice over and over. On a staging site, use a separate invoice prefix or a separate test organization to avoid conflicts with live invoices.

Checking the Result After Launch

Once your test order succeeds, the work is not over. During the first few days after launch, check not just whether invoices exist, but whether the data quality is correct. An accounting integration can look successful until you realize that shipping is being posted to the wrong account code or that all payments have been recorded against one account even though the accountant expected something else.

What to Review in WooCommerce

In WooCommerce, open individual orders and review the Order Notes. You should see entries for invoice creation and payment, or at least a clear error message. If no notes appear, check the event that is supposed to trigger the export. The order may not have reached the required status, or the action may be configured as manual.

Also check whether the plugin is making unexpected repeat attempts. If you manually resend data, make sure you understand which invoice in Xero will be updated and whether it has already been marked as paid. Use the WooCommerce Xero log for debugging, but once the setup is stable, it is better to disable excessive logging so you do not keep unnecessary technical data.

What to Review in Xero

In Xero, open the created invoice and verify the contact, product lines, quantities, SKU or Item Code, shipping, discount, tax, total, invoice status, and payment account. If you use zero rates, make sure they are displayed exactly the way your accountant expects. If you use multiple currencies, check whether your Xero plan supports the required currency and whether that currency has been added to the organization.

It is helpful to agree with your accountant on a "first week review" process: each day, choose a few orders from different scenarios - a normal order, an order with a discount, an order with shipping, an order with zero tax, an order with a refund - and reconcile them manually. That quickly shows which rules are working and which scenarios need a separate process.

Mini Checklist After Day One

• Invoices are created at the right time, not too early.
• Payments are applied only when the order can genuinely be treated as paid.
• All required account codes are filled in and match the correct Xero account types.
• Taxes match by both name and rate, including zero rates.
• SKUs are not causing Item Code errors.
• Order Notes contain enough information to troubleshoot issues.

Safe Adjustments and Careful Workflow-Specific Tweaks

WooCommerce Xero is not the place for hacks. The integration sends financial data, so any customization should be small, reversible, and based on documented filters or standard WordPress practice. If a problem can be solved through configuration, configuration is the safer path.

When Code Is Appropriate

Code makes sense only when the WooCommerce Xero documentation explicitly describes a filter or snippet for a specific behavior. For example, the documentation includes filters for changing the invoice XML, invoice date, due date, line item description, and line account code. But changes like that should be introduced only after agreement with the accountant, because you are altering the data that will be sent to Xero.

For most stores, it is safer to begin with a no-code setup: correct account codes, the right Send Invoices mode, the right Send Payments mode, accurate tax rates, clean SKUs, and Debug enabled only during launch. Save code-level changes for narrow cases.

Temporarily Clearing the Tax Rate Cache

The WooCommerce Xero documentation describes a situation where a tax rate has already been corrected in Xero, but invoices still keep showing the old value. The cause may be a transient with the key wc_xero_tax_rates. Start with the safer approach: use a transient management plugin or wait for the cache to expire. If the site uses persistent object cache and the transient is not visible, you can delete the key once with a small snippet.

Add the code temporarily through Code Snippets or a child theme, load the site once, resend the test invoice, and then remove the snippet. Do not leave this code in place permanently.

add_action( 'init', function() {
    // Temporarily clears the WooCommerce Xero tax rate cache.
    // Remove the snippet after verification.
    delete_transient( 'wc_xero_tax_rates' );
} );

The check is simple: after removing the transient, resend the test order or create a new test invoice and compare the tax rate in Xero. If the rate is still wrong, the issue is not the transient but the rate name, percentage, product tax class, or account code mapping.

What Not to Do

• Do not edit the plugin's own files, because updates will overwrite your changes.
• Do not alter the invoice XML through a filter unless you understand the accounting impact.
• Do not send real orders from a test copy of the site into a live Xero organization without a prefix or a separate test workflow.
• Do not enable automatic payment export if the order may change after payment.
• Do not try to force the standard plugin into acting like a full two-way inventory sync if the documentation only describes reducing existing items in Xero.

Contacts, Coupons, Refunds, and Older Orders in Real-World Use

After the initial test, the next issues are usually not technical - they are accounting-related. One order went through, the invoice was created, and the payment was applied, so everything looks fine. But a few days later you start seeing orders with discounts, repeat customers, company names in billing data, zero tax, refunds, or older orders that accounting wants imported retroactively. It is better to think through those cases before launch, because they directly affect data quality in Xero.

Customer Contacts and the Risk of Duplicates

WooCommerce Xero looks for a contact in Xero based on the order data or the user profile. If it does not find a match, it creates a new contact. That is convenient for automation, but not always ideal for the accounting database. In a B2C store, customers often buy once, use different email addresses, or type their names in different ways. In a B2B store, the company name, VAT ID, address, and ensuring repeat orders map to the same contact usually matter more.

The Use customer email in contact name option helps when Xero already has a contact with a similar name or company. The email is added to the name only when there is a conflict, so one customer can be distinguished from another. That reduces the risk of overwriting data, but it does not replace a contact management policy. If accounting wants to consolidate buyers by company while the store stores different employee email addresses, discuss that in advance. In some cases, it is better to manage key B2B clients manually in Xero and use the plugin only for standard orders.

Working check: create two test orders with the same name but different email addresses. See how WooCommerce Xero finds or creates the contacts, then decide whether that behavior works for your accounting process.

Coupons and Discounts: What the Accountant Will Actually See

The plugin sends the discount amount through the invoice lines. The documentation shows that it can reflect percentage discounts, fixed cart discounts, fixed product discounts, and multiple coupons. But the coupon code itself does not become a core entity inside Xero as a marketing identifier. For accounting, the discount amount is usually what matters. For marketing, the code, campaign, channel, and conversion matter. Those are different jobs, and they should stay separate.

If the accountant needs to understand why the order total is lower than full price, a correct discount line is enough. If the marketing team wants reporting by promo code, use WooCommerce reports or separate analytics. Do not try to turn a Xero invoice into a marketing campaign report if the integration only transfers the financial result of the discount.

Refunds and Adjustments

Refunds need an especially careful process. The official WooCommerce Xero documentation discusses what happens to the invoice when a refund is issued, but before you go live, you still need to test your actual scenario: full refund, partial refund, shipping refund, and refunding a discounted product. What matters is not only whether an adjusting document is created, but also how your accountant wants refunds represented in Xero.

If refunds are rare in your store, you can keep them under manual review: orders are created automatically, but the accountant reviews the refund. If refunds are common, do not launch the integration without a separate test. Create a test order, send it to Xero, apply a refund in WooCommerce, and see what entries appear in Xero and in Order Notes. If the result does not match your accounting policy, a clear manual procedure is better than hoping the automation will somehow work itself out.

Older Orders and Bulk Sending

The Woo documentation says that existing orders can be synchronized manually. For a single order, that is simple: open the order, choose the Send Invoice to Xero action, and apply it. For larger volumes, it mentions Zapier transfer and AutomateWoo with the Trigger Order Action action. But bulk export of old orders is a high-risk area.

The reasons are straightforward. Older orders may already have been entered into Xero manually, invoice numbers may differ, tax rates may have changed, products may now use new SKUs, and some orders may already be partially refunded. If you send a large batch without review, you can easily end up with duplicates, Item Code errors, or invoices that accounting then has to untangle manually.

A safer approach looks like this:

1. Choose one older order that is definitely not already recorded in Xero.
2. Send it manually through the order action and verify the invoice.
3. Choose a second order with a discount or shipping and repeat the check.
4. Agree with your accountant on which dates, numbers, and prefixes should be used for historical documents.
5. Only after that should you plan batch sending through AutomateWoo or another tool.

If you are unsure, it is usually better not to import older orders automatically. For historical data, it is often safer to leave already closed accounting periods untouched and use WooCommerce Xero only for new sales from the go-live date forward.

Compatibility with WooCommerce Workflows and the Site Environment

An accounting integration sits close to WooCommerce's most critical processes: checkout, order statuses, payment gateways, emails, refunds, coupons, taxes, and order storage. That is why compatibility should be evaluated not just by WordPress version, but by the way your actual store works.

Order Statuses and Custom Workflows

Standard WooCommerce statuses are familiar to most integrations, but many stores add their own: Awaiting fulfilment, Ready to ship, Paid manually, Pre-order, or localized equivalents. If the plugin relies on standard payment or completion events, a custom workflow may shift the timing of invoice export.

Check which status in your store truly means the order is ready for accounting. For some stores, that is the moment payment succeeds. For others, it is when the warehouse has packed the order. For B2B orders paid by invoice, it may be a manual manager review. The Send Invoices setting should reflect that actual logic, not the habit of "turning automation on right away."

HPOS, Cache, and Admin Logs

The WooCommerce product page lists compatibility with High Performance Order Storage. That matters for modern stores where orders are stored in separate tables. But compatibility on the product page does not replace testing on your own site: payment gateways, custom statuses, PDF invoice plugins, and snippets may all add their own fields and actions.

Front-end caching usually should not interfere with invoice export, because the event happens in the admin and server-side order logic. But object cache can affect transient data, including the tax rate cache. So if you see strange tax mismatches, check not only your Xero settings but also persistent object cache. Woo documentation includes a separate recommendation for the wc_xero_tax_rates transient.

Site Copies and the Risk of Duplicate Invoices in Xero

If you test WooCommerce Xero on a copy of the site, be careful. That copy may contain real orders, real settings, and real numbering. If you connect it to a live Xero organization and send an order without a prefix, you can create a duplicate invoice or a conflict with an existing document.

For a site copy, use one of the safer options: a separate Xero test organization, a separate invoice prefix, manual Send Invoices mode, or test orders that are easy to distinguish from live ones. After testing, verify that the site copy does not continue sending events to Xero automatically. This is especially important if the copy still runs background jobs or cron events.

PDF Invoice Plugins and Accounting Numbers

Stores often use separate plugins for PDF invoices, packing slips, or local tax documents. WooCommerce Xero does not have to match their numbering logic. If you have an official invoice number in WooCommerce and a separate invoice number in Xero, decide in advance which number will be primary for accounting and which one the customer will see.

The WooCommerce Xero documentation includes a filter for removing the WooCommerce Invoice Number so that Xero can generate its own number. That is not a universal recommendation, just an example of a possible customization. It should be used only after checking with your accountant and the legal requirements in your jurisdiction. In most cases, it is safer to understand your current numbering scheme first than to change it with code.

WooCommerce Xero Errors and Symptom-Based Troubleshooting

When something breaks, do not start by reinstalling the plugin. In most cases, the cause is visible in the order notes, WooCommerce logs, or Xero settings. Work through the chain methodically: symptom, where to check, likely cause, fix, retest.

The Connection Button Is There, but the Connection Fails

Symptom: after clicking Sign in with Xero, authorization ends with an error or the connection status never changes to OK.

What to check: exact Redirect URI match, correct Client ID and Client Secret, the selected Xero organization, the app type Web app, and the OAuth scopes option in WooCommerce Xero settings.

How to fix it: save the correct Redirect URI in Xero, copy the Client ID again, generate a new Client Secret, choose the correct scopes option based on the app creation date, and authorize again. If the app was created using a demo organization, create a new app for the live organization.

invalid_grant Error When Sending Invoices

Symptom: the integration used to work, but now sending an invoice returns the error invalid_grant.

Likely cause: according to Woo documentation, this usually points to a broken connection to Xero. The token may also have expired if the store has not communicated with Xero for a long time.

How to fix it: open WooCommerce > Xero, reconnect the site to Xero, and rerun the test with one order. Do not change account codes or taxes until the connection is restored.

Invoices Are Created, but Payments Are Not Exported

Symptom: the invoice appears in Xero, but no payment is applied.

What to check: the Send Payments setting, the order status, the Payment Account in WooCommerce Xero, and the Enable payments to this account permission in Xero.

How to fix it: make sure the account code exists, the account type supports payments, and Xero allows payments to that account. Then create a new test order. Keep the limitation in mind: the standard integration uses one Payment Account for all payment gateways.

The TaxType Code Cannot Be Used with This Account Code Error

Symptom: the Order Notes show a Xero error saying that TaxType cannot be used with the specified account code.

Likely cause: the account type used for shipping or fees does not match the Treat Shipping As or Treat Fees As setting, or the tax rate does not fit the selected account type.

How to fix it: check the account type in the Chart of Accounts, then choose a shipping and fee mode in WooCommerce Xero that matches Xero's expectations. After updating the setting, create a new test order or resend only where the invoice can still be changed.

The Tax Rate in Xero Does Not Match the WooCommerce Order

Symptom: the invoice is created, but the tax rate shown in Xero is wrong or does not match what the accountant expects.

What to check: the rate name in WooCommerce, the rate name in Xero, the Append Rate Percentage When Matching setting, zero-value rates, and the wc_xero_tax_rates tax rate cache.

How to fix it: align names and percentages exactly. For a zero rate, use Match Zero Value Tax Rates and make sure the product is treated as taxable with the correct tax class. If the rate was corrected recently, clear the transient safely and rerun the test.

Item Code Error When Sending a Product

Symptom: Xero rejects the invoice with an error related to Item Code.

Likely cause: inventory item export is enabled, but the WooCommerce SKU does not match the Item Code in Xero, or the product is not configured as the expected item.

How to fix it: compare the SKU and Item Code character by character. Check product variations, because the issue may not be in the parent product but in a specific variation. If inventory tracking in Xero is not needed, temporarily disable Send Inventory Items and verify whether the invoice can be created without that detail.

The Invoice Is Already Paid and Cannot Be Changed

Symptom: Xero says the invoice is not in a valid status for editing.

Likely cause: the invoice is already marked as paid in Xero, was created manually, or was sent from a staging site using the same number.

How to fix it: do not try to force-overwrite a paid invoice. Check your invoice prefix, separate test orders from live orders, and handle corrections to already paid documents according to your accounting rules inside Xero.

When WooCommerce Xero Is the Right Choice

WooCommerce Xero is worth using if you need a direct, understandable bridge between WooCommerce orders and Xero invoices, and your store's accounting model is reasonably close to what the plugin supports. It handles the core scenario well: "order appears - invoice is created - payment is applied - the order contains a note for verification." For many stores, that is enough, especially when order volume is moderate, taxes are configured carefully, and payments can be tracked through a single Xero account.

You should not expect the plugin to solve a complex accounting architecture on its own. Multiple currencies, multiple payment gateways, fees, refunds, zero rates, inventory items, and older orders all require separate validation. If those scenarios are critical, test them first and compare alternatives. But if your main goal is to eliminate manual order transfer and keep Xero accounting closely aligned with WooCommerce, you can download WooCommerce Xero, install the plugin in a test environment, and work through this guide step by step.

The safest final test is simple: after a test order, you should see the same financial picture in WooCommerce and Xero, clear order notes, and no hidden assumptions that the accountant will later have to fix manually. If that standard is met, the integration is ready for a careful production rollout.