Xeroom Installation and Setup Instructions
Xeroom is a WordPress plugin that links purchase orders and inventory data in Woocommerce to the Xero online accounting application. The Xeroom plugin will post purchase order invoices to Xero and create new product lines if they don’t already exist. The prices, taxes, discounts, coupons, product code, description, inventory, reference and bank or other payments are taken care of by Xeroom. Simple and variable products can be handled and items on sale have their full price added to the description.
The whole process can be set to run automatically using the Auto Complete option so that any order is placed and paid for online by card or Paypal in Woocommerce will appear in Xero as a completed and paid invoice. It can also update the inventory as a result of the sale in WooCommerce from Xero or the other way around.
Xeroom provides far more functionality than currently exists on other similar plugins and best of all the free version does everything the premium version does apart from not providing the address or inventory functions.
Health warning – Note that Xeroom provides a link between two complex applications, Woocommerce and Xero, that both use rigid and tight security and various other constraints. To install and set it up is not a 5 minute job and requires knowledge of not only your products and setup but also of Woocommerce, Xero, some basic bookkeeping and IT, with the ability to access and change files on the server. Some knowledge of server security and your security plugins is also needed. We only do a limited amount of hand-holding and cannot answer endless questions about the detailed instructions given below. If you do not possess or have access to these skills or have the patience to acquire them and deal with issues that might arise then please do not attempt to use Xeroom as you will be disappointed and then blame us.
Installation & Test Service – The install and setup is a bit convoluted due to the complexity and multiple systems involved. Xeroom offers a lot of flexibility and options, as does Xero and Woocommerce. If you know what you are doing it will take 1-2 hours if everything goes smoothly, 2-3 if it doesn’t. We do offer an installation service from one of our experts for only $99/£70 if you don’t wish to invest your valuable time in doing so. This includes a detailed discovery questionnaire to ensure that you get the best setup possible for your business. We also run some tests and checks to ensure everything is working properly and provide your with 2 weeks for your own testing, feedback and subsequent fixes. You can order this with the licence or buy it separately later if you prefer or if you get stuck which sometimes happens to all of us!
Installation Procedure Overview
- Purchase, Download, Upload, Install & Activate Plugin – When you purchase a licence from here it will be emailed immediately. You will be given a secure download link in the order completion email along with your Xeroom licence key.
- Activate Xeroom Licence – Enter the Xeroom key and submit to activate it, whereupon it will turn green.
- Login to Xero and Create a New App – This will provide you with the OAuth2.0 API credentials ie Client ID and Client Secret that are used to permit secure communications from your site’s Xeroom to your Xero account.
- Copy & Paste into Xeroom – Enter the two Xero app credentials from the previous step and save.
- Connect Xeroom to Xero – Then hit Activate and you get a screen in Xero from which to select your new app. The connection should then be established and you are returned to Xeroom with the green Active button showing.
- Configure other Xeroom settings – Add the other account, bank and sales tax settings from Xero.
- Check your SKU codes – Ensure that the correct codes, descriptions and prices exist in Woocommerce and Xero
- Test & Check Orders – Run some test purchases from your site. Check them both in Woocommerce and in Xero.
- Test & Check Payments – Confirm that payments are being posted correctly.
- Inventory Setup – Ensure that the inventory items that you want to synch is set to be tracked in Xero and managed in Woocommerce. Also set the inventory master for when an order is placed. Then set the Xeroom Global Inventory Synch schedule and test.
Xeroom Version 2.1.0 Installation
Version 2.1.0 was released on 10th June 2020. There are 2 significant changes to version 2.1.0. Firstly it is not encrypted and so no longer requires ioncube to work. Secondly, it uses the latest more secure OAuth2.0 protocol to communicate with Xero. Below we still retain the old OAuth1a protocol instructions for existing customers but this will no longer be supported after September 2020. Version 2.1.0 only works with OAuth2.0.
Xeroom uses the Xero API to make communication calls into Xero from WooCommerce using the OAth 2.0 protocol which is the industry-standard protocol for authorisation. Oauth2.0 uses a very secure protocol called Transport Layer Security. TLS is the cryptographic protocol that provides end-to-end communications security over networks and is widely used for internet communications and online transactions. It is a standard intended to prevent eavesdropping, tampering and message forgery. Common applications that employ TLS include Web browsers, instant messaging, email and VOIP. TLS 1.1 is used by most browsers TLS1.2 is a stronger protocol now enforced for card transactions and we also use it for Xeroom.
The secure pipeline for the messages is setup using a Client ID and a Client Secret which are known as credentials both of which are cryptographically generated by Xero in the App:
- The Client ID is a public identifier for apps. Even though it’s public, it is best that it isn’t guessable by third parties.
- The Client Secret is a secret known only to the application and the authorisation server. It is hidden by Xero once saved and so no longer viewable but can be deleted and a new one created.
Migrating from OAuth 1.0a
Xero does not provide a migration path for public and private apps. If you have an integration using a public or private app you can create a new OAuth2.0 app and migrate your users at any time. The key dates for migrating OAuth 1.0a apps:
- Early December 2019 – No new OAuth 1.0a apps created.
- Mid December 2019 – OAuth 2.0 migration endpoint available to partner apps.
- December 2020 – All certified partner apps required to be on OAuth 2.0.
- March 2021 – OAuth 1.0a will no longer be supported for any apps.
Creating Your Xero Connection
There are 3 steps to this part.
1. Create a New Private Application in Xero
First log in to your Xero account at: http://login.xero.com and go to the Developer Center https://developer.xero.com/myapps where you will see a list of all your connected apps. Select New App on the top right hand side. You will get the screen above, so enter the details as follows:
App Name – Whatever you want to call your app – It cannot have the word Xero in.
Oauth 2.0 Grant Type – Auth code Web App
Company URL – https://www.yoursite.com
OAuth 2.0 redirect URI – https://www.yoursite.com/wp-json/xeroom/v2/oauth_callback
Tick the terms and conditions box and click on create app. The new app should appear although sometimes your screen will appear to hang with a spinning ball so after 20 secs just refresh your page and your new app will show.
Click on Generate a Secret and then don’t forget to Save and your new app is created. The Secret will disappear and no longer be retrievable so copy it somewhere, you can however always create a fresh Secret.
2. Add Your App Credentials to Xeroom
Then copy and paste both these credentials into your Xeroom settings. Also keep a copy in case you need them as your Client Secret will not be visible in your Xero App again. You can generate a new one if you need it though. Then scroll down and click on Submit.
3. Connect Xeroom to Your Xero App & Organisation
Scroll back up and click on Xero Authorize. Xeroom will then attempt to connect to your new app. It will come up with a new screen with your newly created app from the previous step. It will ask which Xero organisation you wish to connect your app and allow access to. You can select the organisation from the drop down list and list any existing connection at the bottom. You can also disconnect from an organisation here too. If the connection is successful then it will take you back to Xeroom and the Xero Connection Status will show green.
Troubleshooting OAth2.0 Connection Errors
If you get a general 500 error screen then it means that you are not connecting or to be exact, your server is not connecting to Xero’s server. Please check the following:
- Are your URI settings correct? Go back and double check them all and especially that you have saved in both places AFTER you generate the Client Secret. Also try deleting the new app and recreating again in Xero.
- Version 210 uses wp-json which is the REST API for your site. It is a virtual address and the status can be checked by going to tools/site health. Some plugins do disable the Rest API and it has been known to be left out of the php modules in a server build so do ensure that it is there and running properly.
- Check that you don’t have another Xero app with the same name or that you have exceeded your limit of apps which is 2 unless they are Xero certified, Xeroom isn’t yet but we are working on it!
- Check your firewall for possible blocks or a changed or alias URL for your website.
We cannot troubleshoot your settings as there are no tools available to us and so cannot help but Xero support can if you supply them with the app details you used to create it on a support ticket.
Xeroom Version 2.0.8 and Older Installations
FATAL ERROR message on activation – You will get a page of garbled text and have to delete the plugin using FTP if you use the wrong php and ioncube loader versions. Versions 2.0.8 and older are encoded with ioncube and your server must have this installed for Xeroom to run. Most hosters have this but if not ask your host to install the latest free version of it as it is useful for other WordPress plugins as many use it.
php version – We only support versions of php 7.2 and 7.3. If you are running on an earlier versions of php it will not work and give a fatal error. You can go to cpanel and upgrade the php version yourself or speak to your hoster to do it.
This version uses a new Xero public security certificate valid until 12th Feb 2023 which is in the download and also given here. You will need to either refresh your Xero app with the new certificate in the developer center or before upgrading backup and restore your previous certificate to the /library/certs folder as the upgrade will overwrite it. You can install the plugin WP File Manager to access your files without having to use FTP.
Xeroom remembers all your settings including the Xero keys in the database when you delete it and install a new version.
WordPress.com does not support ioncube decoders and is very restrictive about their use so Xeroom will not work on their server.
OAuth1a Protocol – Now Deprecated
Xeroom uses the Xero API to make communications into Xero from WooCommerce. This uses a very secure protocol called Transport Layer Security. TLS is a cryptographic protocol that provides end-to-end communications security over networks and is widely used for internet communications and online transactions. It is a standard intended to prevent eavesdropping, tampering and message forgery. Common applications that employ TLS include Web browsers, instant messaging, e-mail and voice over IP. TLS 1.1 is used by most browsers TLS1.2 is a stronger protocol now enforced for card transactions and also used for Xeroom.
The secure pipeline for the messages is setup using a set of long oauth public and private Xero API security keys. The keys are manually created on installation within the Xero private application of your account. They are unique to your Xero account and to the security certificate that sits on your WooCommerce website’s server that is going to communicate with Xero. This certificate must be valid and in-date and can be the one shipped with Xeroom or your own specifically created on. So all three must match up in order for this to work ie the certificate on your server must be used in the Xero private application to create the keys that are then used in Xeroom. These steps are explained in more detail below.
OAuth1a – Xero Connection
Xeroom ships with a public/private key pair that can be used to generate the Xero API keys. If you prefer your own key pair then you can follow the instructions here. You need to set these keys into a private application within Xero that allows them to work with your specific instance of Xero. It is effectively the lock to use your keys in. To do this log in to your Xero account at: http://login.xero.com and go to the Developer center at: https://developer.xero.com/myapps?privateAppCreation=true. Note that the previous url to access this http://api.xero.com no longer provides access since Xero is in the process of deprecating Outh1a and replacing it with Oauth2.
Sometimes for some reason the Private App button doesn’t show in Xero http://prntscr.com/r3jkjm but if you clear your cache and cookies it should do so. I just checked and had to log in twice to Xero as the first time it didn’t show as the url must be this https://developer.xero.
Select the My Apps menu item and then Click the “Add Application” button (you will not need to do this step if you have not previously set up an application)
Fill out the form with the following options:
- What type of application are you developing? Select “Private”
- Application Name: Enter Xeroom or the name of your WooCommerce site, this is for reference purposes only.
- Please select which organisation your application can access: Select which Xero company to access. The extension can only access one company at a time.
- X509 Public Key Certificate: Paste the certificate file from the public key that you can download here into the app. Note: Certificate files begin with the text “—–BEGIN CERTIFICATE—–”
OAuth1a – Creating API Keys
Once you save it the application will be created along with the unique secure communication API credential keys. You can then copy and paste these keys into the Xeroom settings page as described below ( ie the consumer key and consumer secret known as the Oauth credentials)
Download, Upload, Install & Activate Plugin
Download Xeroom onto your pc from the link sent when you purchases it. Then go to the plugins page and upload it. Once it says install successful then click on the activate button that will appear. If the installation and activation process causes errors this is either due to a conflict with your other plugins or else a security setting in your htaccess files set from a plugin. It can also be a glitch so retry it. Disabling the plugins by renaming the plugin directory is a quick way to establish that. You will need a default version of your htaccess files for the root and wp-content directories to rule out issues with htaccess. NB: Changing the htaccess should be treated with great caution as it can easily disable your site completely. It should only be done by an IT expert who knows what they are doing.
Activate Xeroom Licence
You will notice the Xeroom logo has now appeared on the left hand menu. Click on it to take you to the Xeroom configuration screen that is shown below. Enter your Xeroom licence key and hit Submit. If you don’t have one then please go to the shop above and buy one. It will be immediately emailed to you. If the licence is valid you will get the success message below. The Trial licence is no longer offered as we provide a 30-day money back period so ignore that box.
If you get “Oops something went wrong” it means that it is already activated with another key in which case refreshing the screen should clear the error. If this is not the case then please contact support. If you get the following error then it means that your licence key is not active. It can also mean that it is already activated with another key in which case refreshing the screen should clear the error or that your key is being used on another website (keys are restricted to use on one website). It can also mean that there was a comms error communicating with our server so try it a few times to rule that out. Finally, in rare instances it can be that both cURL and curlSSL are missing on your server. These need to be installed and usually are as standard but sometimes a host may have a non-standard setup.
Deprecated – OAuth1a Credentials
Copy and paste the Consumer Key and Secret Keys from the OAuth section of the Xero application that you created earlier into the appropriate boxes in Xeroom, click “Submit” to save them and then if everything has been done correctly the “Active” status button will turn green. If you find invoices are not appearing in Xero then it is 95% likely to be that this has not been done correctly and will give an Oauth error message in the debug screen. The quickest way to clear it is to simply repeat the key generation procedure carefully checking each step of the way. Also especially check that the certificate used is correct and in-date (the Xero application tells you this when you upload the certificate).
Configure Xeroom Settings
The Xeroom settings then need to be made. The accounts MUST match those in your Xero account otherwise this will not work. The accounts in Xero cannot be of any old type but MUST be of the correct Account Type ie Expense/Revenue etc. To be sure look in the Chart of Accounts in Xero and ask your bookeeper or accountant to double check these.
Sales Account – The account to which the sales are posted. Usually 200 in Xero.
Shipping/Carriage Costs – The account that Revenues charged to customers is posted to. Note this is not the account your carriers costs sit in. This can be 200 or create a new one in Xero for 210
Bank Account – This is the Xero code for the bank account and must exist and no have zeros as its numbers otherwise no payments can be posted. Xero does not number these by default so number it 100 or 110 in Xero and set it here.
Sales Tax Account Name – This is your standard rate GST/VAT/Sales tax METHOD ie not the account no and must exactly match the spelling in Xero as found under General Settings/Tax Rates eg “20% (VAT on Expenses)”.
Inventory Asset Account – The account that manages your inventory. The default is usually 630.
Goods Sold Account – This is the account where the costs of goods sold COGS for any sales made is posted to. It applies the cost of the product as set in Xero to the sales posted in the invoice to create an entry in this account. The default is usually 310.
Synch Inventory Master – Set where you want the inventory master to be. Sales will affect the master directly and the resulting balance flushed to the slave as sales take place. NB There is no global synch of all products – that is due for release in late 2018.
Product and Price Master – The products from orders on Woocommerce have codes that link to Xero. This sets where the prices and descriptions that appear on the invoice in Xero are taken from. If a product doesn’t exist in Xero then Xeroom will create one using the SKU from Woocommerce or if that doesn’t exist then the Product ID.
Create Invoices as draft/awaiting payment – Do you want to create the invoice as a draft status which needs to be authorised or as awaiting payment which is approved but can still be edited and voided. The next stage in Xero is paid which cannot be deleted as the payment and other book keeping entries have been made. The only option to remove it is to reverse it by creating a credit note.
Post Credit Note when order is cancelled – Do you want a CN to be automatically generated in Xero once an order is cancelled in Woo?
Use Extra Sales Accounts – Do you want to be able to break down sales in Xero by geography or by product category. With geography the idea is to use broad zones such as countries or trading blocks such as EC. The same with products it is not intended to handle reporting by individual product (which can be done as a report in Xero) but for groups of products ie categories. Create the separate accounts in Xero and then use this option to map them. Note Xero doesn’t support sub-accounts. It is not possible to mix and match geographies and categories. You can have up to 10 separate accounts for each.
Auto Complete – Do you want payments to be posted automatically to Xero once payment is confirmed by card or paypal? This means that instead of appearing as invoices awaiting payment in Xero which can be further edited in Xero they will appear as Paid invoices which cannot be changed. This doesn’t complete the order in Woocommerce but leaves its status as Processing and so is really Auto Pay. If set to no then only when the order is completed in Woocommerce will it have the payment applied in Xero and become a Paid status invoice.
Xero Debug Link – This will open the debug page which will show any invoices and associated errors that might have happened. Always check this if something is not working correctly.
Products Held Inclusive/Exclusive of GST
By default prices are received by Xero and treated as tax exclusive with whatever GST tax is specified in Xero or copied across then added by Xero. This meant that if you keep your prices as inclusive of GST in Woocommerce then it would be added again on posting into Xero so it was added twice. Xeroom will now pick up whatever the tax setting is in Woocommerce and handle the GST accordingly. Note that there is a setting in invoices in Xero to hard set this if you find that they are not showing correctly.
Note that Woocommerce has to be the master for the prices because if you set Xero to be master then you will have to set Xero to have prices exclusive of GST otherwise GST will be added twice due to the fact that Xero always adds it on even if it receives the prices gross.
Test & Check Orders
Run some test purchases from your site. Check them both in Woocommerce and in Xero. For the free version a typical invoice of would look like this:
Check that the invoice figures match with the Woocommerce order that the order no reference is correct, the tax and shipping figures are correct and also go to the accounts themselves to ensure that the postings are correct. Also test with coupons and with and without shipping.
Test & Check Payments
Complete the order in Woocommerce by clicking on the complete icon on the right of the order screen. The status will change to a tick on the left.
Then check that the payment has been posted correctly into the payment or bank account. This is how a typical Paid invoice would look with the free version.
This is how a completed Paid invoice would look with the Premium Version showing the full address and no Xeroom reference.
Manual Posting of Orders & Payments to Xero
We have added 2 buttons to the bottom right of the Woo order screen so that if you enter any orders manually ie not from the front-end shop, then they can be posted along with the payment to Xero.
Refunds – Automatically Generate Credit Notes
Once an order has been paid for and completed (which can be automatically done when the customer checks out and pays by card or paypal – see the Autocomplete option to yes) it is then possible to automatically generate a credit note in Xero should the order be cancelled. Use the order actions dropdown menu in the top right hand side to do this.
Errors & Debugging
Licence not authenticated – If you are using the free version then try a new or different email address. If you are using a premium licence then it might have expired and need renewing so please email me to check.
No invoice appears in Xero – The invoice should appear under the Invoices Awaiting Payment under Account -Sales-Invoices. If there is nothing there then there is an issue with the communications which is almost certainly due to your Xero Api keys being wrong. Try recreating them using the step-by-step procedure above. Also check the Debug screen in Xeroom. We are going to add an automatic check of the Xero comms.
Debug Screen – If you click on the Debug button in Xeroom settings then it will open up a screen showing the last invoices that had errors along with messages.
When are orders sent to Xero?
Completed orders are triggered and sent to Xero during the checkout process when the customer completes the checkout successfully. This results in the action “woocommerce_checkout_order_processed”. A note is made on the order in Woo that it has been sent to Xero.
When are payments sent to Xero?
Payments are triggered and sent to Xero when the payment is complete. This is from the action “woocommerce_payment_complete”.
Can I synchronize existing orders?
Yes you can use the Bulk Data Loader feature – see the separate user instruction page on the menu above.
What happens if the tax rate is not set up correctly?
It’s important that setup tax in WooCommerce matches the setup tax in Xero because Xero validates line totals. If Xeroom cannot find a matching tax rate then it will not make an error but create a new one using the % sent across but will not have a name and will not be treated correctly in xero.
What happens if an invoice fails?
If you have tested everything then this should never happen. You can check whether the order has been posted or not by looking at the order notes in Woo.
Why aren’t my 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.
Debug shows o oauth_problem=….
This means that Woo is not communicating with Xero due to the Xero API keys and/or security certificate being invalid or not matching. The keys must be created with the certificate publickey.cer file that sits on your server install. Also the publickey.cer must have not date expired.
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.
Error sending invoices: “TaxType code ‘xxx’ cannot be used with account code ‘yyy’
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’.
The Xero shipping account that is set in Xeroom is not one of “Revenue” type in Xero. Go to Xero and COA and edit it to change the account type or else create a new one of the correct account type.
You must also be using at least version 1.7.7 of the plugin.
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.
Error: XERO: Invoice not created. OAuth Error: token_rejected | The
organisation for this access token is not active
This error happens when the API application was created with the wrong organization. Go to https://api.xero.com/, Click on My Applications, then the application you created to connect your WooCommerce site. If the Selected Organization is “Demo Company” you’ll need to delete this application and recreate another one.
Xero can’t find the certificates
If you have created your own certificates that you used to create your Xero Oauth credentials in the Xero application but did not copy them into the xeroom/library/certs directory.
Frequently Asked Questions
Q: Is Xeroom free?
A:Yes there is a free version and also a paid for premium version. The free version performs all of the premium version functions apart from inventory. It also has a line on the invoice in Xero stating produced by free version of Xeroom. The premium version is available as an annual licence with or without support. Installation is available as an option as is configuration of your Xero accounts.
Q: Why do I need a xero.com application?
A:The Xero application is essential in order to provide the api consumer key and api consumer security keys without which the Xeroom plugin cannot work. This enables secure and correct communications to take place between your on-line Xero account and your WordPress Woocommerce site.
Q: I already have a xero account, What’s next I need to do?
A: You have to create a new application by visting this link http://www.app.xero.com/ and get the two consumer keys referred to above to run your plugin.