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. 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 in the case of unforeseen or unusual problems IT, with the ability to access and change files on the server. Some knowledge of server security and your security plugins may also be needed. 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 as Xeroom offers a lot of flexibility and options, as does Xero and WooCommerce. We offer a full installation and test 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 as well as creating any extra accounts you need in Xero and running tests and checks to ensure everything is working properly. You can order this at the time of purchase or add it on afterwards if you prefer.
Reviews & Free Version – We provide a free version of Xeroom that provides a good level of functionality. This has taken considerable time and cost to develop. If you are making use of the free version all we ask is that you take a minute to give us a good review and/or to upgrade to the Premium version. If you have problems then please ask us by posting a question on the support site so others can see the answers and give us a chance to help fix it. We have had a bad review by someone who hit a security problem and did not even bother to install it yet alone use it. That is not only unfair but dishonest! Good reviews will help ensure our success and that we continue to provide future versions of Xeroom for free and paid versions for great value. You can add a review here.
- Xero sign up – Take out a demo or paid subscription to Xero.
- Xero Setup – Configure your Chart of Accounts, Tax settings, inventory etc and bulk upload data from existing system.
- Xero Connection Keys – Use our keys which come with the plugin or if you prefer create your own Xero Public/Private Key Pair.
- Generate Xero Connection API Keys – Configure a new Xero application and use the key pair as a seed to generate the Xero API public and secret credentials which are used for secure communications between Woocommerce and Xero.
- Install & Activate Plugin – in normal fashion either from the plugin page, new, search.
- Activate Licence – Use either free or Premium. For a free licence just enter your email, submit and it will activate. For a Premium Licence Key you can purchase from here and it will be emailed immediately after checkout and making payment.
- Configure Xeroom Settings – Using the Xero credentials and account settings from 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 applied correctly.
- Errors – Common errors and debugging
Note: Both cURL and curlSSL need to be installed on your server. Ask your host if they have these modules installed.
Xeroom Version 2.0 Release Notes
We released version 2.0.0 on March 22nd which has many useful enhancements. We have had to encode this version using the popular ioncube app as we have found incidents of theft of our code which has cost us a considerable sum to produce.
1 This requires version 5.0.3 of WordPress and version 3.5.6 of WooCommerce or above to run so do not upgrade if you are using older versions of these.
2. 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. Version 2.0 of Xeroom is 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.
3. php version – We support versions of php from v 5.6 to 7.2 (the latest). 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.
4. ioncube loader version – The xeroom download from WordPress is coded to run with ioncube loader 10.2 (the latest) and php 5.6-7.2. If you are using loader v 10.0 or 10.1 then you need Xeroom encoded for php 5.6 which will run php 5.6 to 7.0 and can be downloaded here. If you are on php 7.1 or 7.2 then you need to either upgrade loader to 10.2 or downgrade php to 7.0. If you have loader v 9 you are definitely in the stone-age and should go and seek candlelight first!
5. We have done lots of testing but if you do encounter any errors please take a screenshot and email it to us so we can investigate. This is the first encrypted version so there may be a few hidden errors that get triggered by your setup. If you get fatal errors then you can just reinstall the previous version 1.5.2 which can be downloaded here.
6. 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.
7. Xeroom remembers all your settings including the Xero keys in the database when you delete it and install a new version.
8. WordPress.com does not support ioncube decoders and is very restrictive about their use so Xeroom will not work on their server.
Communications Between WooCommerce and Xero
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.
Xero Connection – Setting Up A Private Application
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.
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—–”
Get Your API Keys For Xeroom
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)
Install & Activate Plugin
In normal fashion either from the plugin page. You can either upload the plugin that you download from this page on the link above or you can search for Xeroom and click on the install button. 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. 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 and should be left to your IT expert who created your site.
You will notice the green 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. The first thing to decide is whether to use the free or Premium version.
Free version – To obtain a free version licence simply click the box and enter your email address then click submit twice which will activate in a few seconds and give you a success message.
For a licence key you need to make the purchase from the shop above on this site. The key is usually generated on purchase and returned in the order. This should be entered into the box and click submit. Again you will get a success message.
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 with the Premium licence key 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). If not please contact support.
Copy Your New Certificates Onto Your Server
Xeroom is shipped with default versions of the public and private certificate pair which will work so long as you use the same private key to create you Xero application below. It is highly recommended that you create your own key pair to use. They will need to be manually copied into the library/certs directory of Xeroom on your server once you have installed Xeroom.
Use OAuth Credentials – Xero Api Keys
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.