Xero for WooCommerce allows you to create invoices in Xero for all sales on your WooCommerce site, and also tracks and sends data on items, shipping, discounts and tax to your records to keep everything in balance.
Requirements ↑ Back to top
- cURL and curlSSL need to be installed on your server. Ask your host if they have these modules installed.
Installation ↑ Back to top
- Download the .zip file from your WooCommerce account.
- Go to: WordPress Admin > Plugins > Add New, click Upload Plugin, select the file you downloaded and click Choose File.
- Install Now and Activate the extension.
More information at: Install and Activate Plugins/Extensions.
Setup and Configuration ↑ Back to top
WooCommerce and Xero setup ↑ Back to top
Xero’s API uses 2-step OAuth to validate all connections.
To set up the connection between your WooCommerce shopping cart and Xero account, there are two steps:
- Generate a Self-signed Certificate (X509) for use with this module; and
- Define your WooCommerce site as a Private Application and allow it to connect to your Xero account.
Step 1: Generating a Private/Public Key pair
The Xero site has detailed instructions on how generate keys for Windows and Mac.
You can download OpenSSL for Windows at Shining Light Productions OpenSSL.
To run the commands below, go to the OpenSSL32 directory on your PC, and change to the /bin directory.
- You may need to open the command prompt with elevated status (Run as administrator)
- You might need to restart the computer, if OpenSSL was recently installed
OpenSSL comes shipped with Mac OS X. You can use Terminal to run OpenSSL (search for ‘terminal’ using the search bar in the top right of your screen on your desktop) to open the terminal window and then run the commands below.
Open SSL comes shipped with most distributions of Linux.
Use a command line prompt and the following commands to generate a private and public key pair.
1/ The following command will generate a private key file named “privatekey.pem” in the current directory
openssl genrsa -out privatekey.pem 1024
2/ This command uses the previously created private key file to create a public certificate to be used when setting up your private application in the next step. You are asked to provide 7 pieces of information about your company that will be included in the certificate file: Country Name (2 letter code), State or Province Name (Full name), Locality (city), Organization Name (company), Organizational Unit Name (section), Common Name (Your name), Email Address. Days is set to 1825 (5 years) so this step need not be replaced every year.
openssl req -newkey rsa:1024 -x509 -key privatekey.pem -out publickey.cer -days 1825
3/ To verify the files were created correctly, verify the first line of each file.
The private key will begin with the following line:
-----BEGIN RSA PRIVATE KEY----- The public certificate will begin with the following line: -----BEGIN CERTIFICATE-----
Step 2: Set Up A Private Application in Xero
- Log into your Xero account at: https://login.xero.com
- Go to the developer area at https://developer.xero.com/myapps?privateAppCreation=true
- Click Add private app.
- Complete the form with the following options:
- App name: Enter the name of your WooCommerce site.
- Organisation: Select which Xero company to access. The extension can only access one company at a time.
- X509 Public Key Certificate: Paste the certificate file you created in Step 1. above. Note: Certificate files begin with the text “—–BEGIN CERTIFICATE—–”
- The Payroll API is not integrated with this plugin so it doesn’t need to be activated.
- Click Create app. You are then taken to the App Details page.
- The App Details page has a box titled OAuth 1.0a Credentials showing the Consumer Key and the Consumer Secret. These will be used in the next step.
Xero setup on the WooCommerce site ↑ Back to top
Setup OAuth Credentials
- Log in to your WordPress dashboard and go to WooCommerce > Xero to configure the required settings.
- Enter Consumer Key and Consumer Secret with the OAuth 1.0a Credentials retrieved when registering your private application with Xero in the previous step.
Add the certificate files
Select Public Key and Private Key files for upload with the Browse buttons. Selected files will be uploaded after pushing Save.
Set Up Default Account Codes
Invoices and payments sent to Xero need to be associated with account codes in your company’s Chart of Accounts. This is a required part of setup.
Find the Chart of Accounts via Accounting > Chart of Accounts or Accounting > Advanced in your Xero dashboard:
Xero provides a standard set of account codes that you can modify as necessary (default codes will vary by country):
Note: The Tax Rate associated with the Xero account needs to match the tax rate setup in WooCommerce.
- Sales Account – This account collects all sales of items in your store.
- Shipping Account – This account collects all shipping charges.
- Fees Account – This account collects your payment gateway fees.
- Payment Account – This account collects all payments made. This account either needs to be Account Type “Bank” or have “Enable Payments to this account” checked in the Edit Account Details popup.
- Rounding Account – This account collects all the rounding corrections.
Account codes must be entered at WooCommerce > Xero within your site:
Important: All Account Code fields must be entered in order to send invoices to Xero.
Read more about setting up account codes at: Settings: Chart of Accounts.
Miscellaneous Settings ↑ Back to top
- Tick the box to have WooCommerce send invoices automatically to Xero based on the order status. Recommended: Payment Completion.
- Tick the box to have Xero mark the associated invoice as PAID based on this setting. You may need to turn this off in case you synchronize payments in another way such as the PayPal to Xero integration.Important: once a payment is sent for an invoice and the invoice is marked PAID in Xero, it cannot be modified via the API. This means that WooCommerce cannot make any changes programmatically to the invoice. If the invoice is marked PAID in Xero all changes must be done manually in Xero.
Match Zero Value Tax Rates
- This allows you to explicitly match up a WooCommerce tax exempt(0%) tax rate with a Xero tax exempt(0%) tax rate. This helps avoid issues like tax exempt line items showing up as Zero Rated EC Services.
Treat Shipping As
- The costs associated with shipping line items in your WooCommerce orders can be treated either as Revenue or Expenses. You may need to toggle this setting based on your Xero Chart of Accounts settings to avoid errors.
Send Inventory Items
- Tick the box to send the WooCommerce product SKU to Xero as an Item Code field. This allows you to reduce inventory numbers defined in Xero when each item is sold.
- You must have a corresponding Inventory Item Setup in Xero for this to work properly.
- Note that this is not an “Inventory Sync” as this will only reduce the existing quantity of inventory items in Xero when a corresponding item is sold. It will not synchronize your Xero and WooCommerce inventories if the inventory quantity is adjusted in either system.
Orders with zero total
- Tick the box for Orders with zero total to enable export of invoices for orders that have a grand total of zero.
- Tick the box for the Debug option to enable logging for this extension.
- Log file is located at: /wc-logs/
Usage ↑ Back to top
Orders placed in your WooCommerce store are copied to your Xero account as an approved invoice. When payment is completed (normally immediately), then a payment is added to the invoice making the invoice paid in full.
A note is added to each order in WooCommerce for the invoice including the Xero invoice reference number (Invoice ID).
Here is a sample Xero invoice with payment.
WooCommerce Order Fields Sent to Xero ↑ Back to top
These are the WooCommerce Order fields that are sent to the Xero invoice. Note: If Billing Company field is used, it will be the main name on the invoice. Otherwise Billing First Name and Billing Last Name are used.
- Billing First Name
- Billing Last Name
- Billing Email
- Billing Company
- Billing Address 1
- Billing Address 2
- Billing City
- Billing State
- Billing Postal Code
- Billing Country
- Billing Phone
- Order Date
- Order Number
- Order Item Data: Product name
- Order Item Data: Quantity purchased
- Order Item Data: SKU (if Send Inventory is enabled)
- Order Item Data: Product price
- Order Shipping Charge (Optional)
- Order Discount (Optional)
- Order Tax Total
- Order Total
Invoice Status is always AUTHORIZED. Tax Type depends on the WooCommerce setting.
FAQ ↑ Back to top
When are orders sent to Xero?
Invoices are created within Xero based on the Send Invoices setting found at WooCommerce->Xero.
When are payments sent to Xero?
Payments are sent to Xero based on the Send Payments setting found at WooCommerce->Xero.
Note: when a payment is applied to a Xero invoice the order is marked PAID in Xero and cannot be modified any longer through the API.
Can I synchronize existing orders? ↑ Back to top
Yes, you can, but it’s a manual process. To achieve this, go to WooCommerce > Orders and select the order you want to sync.
Select Actions and choose Send Invoice to Xero. Then select the “>” button on the right.
How do I know if an invoice has been sent to Xero?
Entries are added to the Order Notes area of the order page. There is one message for the invoice and one for payment.
What happens if the tax rate is not set up correctly?
In order for your tax rates in your Xero invoices to be as accurate as possible, it is essential that your tax rates and names in WooCommerce match the tax rates and labels in Xero. If these two tax rates differ you may receive errors when trying to generate invoices/payments.
Xero simply omits the tax rate in my invoices if items are tax exempt. ↑ Back to top
The default behavior of WooCommerce is to completely omit taxes from sending per line-item if the tax is either 0% or the item is not taxable.
If you want the Xero line items to show a zero tax rate(0.000%) you can do the following:
- Make sure the Xero plugin is updated to at-least version 1.7.17.
- Create a new WooCommerce 0% tax rate with a name which exactly matches your 0% rate in Xero. Xero creates a 0% tax rate upon account setup named Tax Exempt so it’s recommended to copy the name exactly.
- Enable the Match zero value tax rates setting on the WooCommerce->Xero settings page.
- Edit your tax exempt products and make sure they’re set to Taxable as well as linked to the zero-rated tax class(or wherever you have the 0% tax rate setup).
- Go to WooCommerce >Settings >Tax and for the option Calculate Tax Based On, choose Customer Billing Address.
What happens if an invoice fails?
If creating the Xero invoice fails for any reason there will be a note added to Order Notes section with the error message.
Typical causes of failure:
- Missing account codes on WooCommerce >Xero settings page. Every account code field needs to be filled out there and matched up with an account from your Xero Chart of Accounts.
- The Xero keys set on the WooCommerce >Xero settings page do not match the ones corresponding to your app.
How do I match the tax rate label to what is on Xero?
By default, a new tax rate label will be created on Xero during invoice creation.
However in some countries this may or may not be the desired outcome. If you need to match the tax rate label from what you have entered in WooCommerce to what Xero already has in the system, you can use the following filter. Add the filter to your child theme’s functions.php file
add_filter( 'woocommerce_xero_create_unique_tax_label', '__return_false' );
Once you have done this, whatever you have set in as your tax rate label in WooCommerce will match what is already existing in your Xero account.
Can I use Xero with my multi-currency store? ↑ Back to top
Yes, if you have a Xero account with multi-currency capability(this usually requires an upgrade).
If you receive an error in the Order Notes related to the currency not being supported, add additional currencies in Xero by going to Organization Settings, click on Currencies and add the currencies available in the store.
Can I map products or product categories to different Xero account codes? ↑ Back to top
This is not yet an option in the Xero plugin, however, it is theoretically possible by creating a custom function which hooks into the woocommerce_xero_line_item_account_code filter. Your custom function would need to check the category ID or product ID and return an integer representing the Xero sales account code(must be a Revenue/Sales account type).
See the WooCommerce hooks documentation for help with utilizing WooCommerce hooks.
Troubleshooting ↑ Back to top
How do I see debug information?
To view debug information make sure the Debug checkbox option is checked in the Xero settings page. You can find Xero logs at WooCommerce > Status > Logs
Why aren’t payments being exported?
If invoices are being created, but payments are not being created, make sure that the Xero account that is used for “Payment Account” has “Enable payments to this account” checked in the Edit Account Details popup.
I am getting an error sending invoices: “Item code ‘xxx’ is not valid”
If you get the following error in the order notes related to “Item Code”:
ERROR creating Xero invoice: ErrorNumber: 10 ErrorType: ValidationException Message: A validation exception occurred Detail: Item code ‘XXXX′ is not valid
Please check your Xero configuration and make sure the inventory item is setup correctly. Here’s a doc on how to set up inventory items in Xero.
I am getting an error sending invoices: “TaxType code ‘xxx’ cannot be used with account code ‘yyy’ ↑ Back to top
You may see the following error in the order notes:
ERROR creating Xero invoice: ErrorNumber: 10 ErrorType: ValidationException Message: A validation exception occurred Detail: The TaxType code ‘xxx’ cannot be used with account code ‘yyy’.
If so, this is related to the shipping account being set to the wrong type in the WooCommerce Xero settings: it must match the account setting in Xero. You can set it in the WooCommerce > Xero settings option Treat Shipping As:
You must also be using at least version 1.7.7 of the plugin.
Line items without VAT applied appear as Zero Rated EC Services in Xero invoices
See the section named Xero simply omits the tax rate in my invoices if items are tax exempt for information on how you can force the Xero integration to match up with a specific tax rate for zero-rated line items.
I am getting an error for payments
ERROR creating Xero payment. ErrorNumber:10| Error Message:Account type is invalid for making a payment to/from
Make sure that the account you specified for “Payment Account” in the Xero settings has “Enable Payments To This Account” checked in Xero.
This will need to be either a Bank account type or a Revenue/Sales account type.
Error: XERO: Invoice not created. OAuth Error: token_rejected | The
organization for this access token is not active
This error happens when the API application was created with the wrong organization. Go to https://developer.xero.com/myapps?privateAppCreation=true and click on the application you created to connect to your WooCommerce site. If the Selected Organization is “Demo Company” you’ll need to delete this application and recreate another one.
When you recreate the application, on the option “Please select which organization your application can access:” be sure to select the correct organization.
Questions and Feedback ↑ Back to top
Have a question before you buy? Please fill out this pre-sales form.
Already purchased and need some assistance? Get in touch with a Happiness Engineer via the Help Desk.