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.
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 which is unfair.
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 data capture 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. Note the Xero connection URI needed for your site to work is generated in bold blue – copy and paste this into the Xero App that you create in the next step.
- 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 Latest Version Release Notes
The latest version of Xeroom is given here https://www.xeroom.com/updates/ along with the last few versions and release notes.
Version 2.1.0 was released on 10th June 2020. There are 2 significant changes to version 2.1.0. Firstly it was not encrypted and so no longer required Ion Cube to work which makes it simpler. Secondly, it uses the latest more secure OAuth2.0 protocol to communicate with Xero which is also simpler. Full details are given below.
Xeroom uses the Xero API to make communication calls into Xero from WooCommerce using the OAuth 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
NB: The URI Format MUST BE CORRECT TO WORK – This is the usual format of the URI but it may be slightly different on your site due to your permalink structure. To eliminate any issues with this Xeroom will give you the exact URI needed for your site to work on the Xero Settings section (see screenshot below).
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 OAuth2.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. The steps below will solve this error 99% of the time.
- Are your URI settings correct? They must be identical to your website including the canonical “www” part.
- Generate a new secret and a new client id in the Xero app. NB: Ensure that you save these credentials in the Xero app and copy and save them in Xeroom too. This generates a new token which sometimes time out or expires and has to match the one in Xero for authentication.
- Try deleting your Xero app and recreating it 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.
- Check that the Xero permissions of the person who made the Xero App have not been changed or deleted by the Xero admin user.
- Check your WP error log in the WP-Content directory (you will need to set WP Debug to on in your wp.config file for the log to be created). This should reveal any conflicts that occur with other plugins. If you find one then please cut and past the error stack and send it to us to fix.
- As an alternative to the previous step look for likely plugins that would be conflicting with it and disable them – or quickest is to disable all of them and see if it clears.
- Check your firewall for possible blocks or a changed or alias URL for your website.
- We cannot troubleshoot your settings as there are no special tools available to us and so cannot help but you can ask Xero support. Make sure you supply them with the Xero user and Xero app details that you created.
- Xero support info for further suggestions https://developer.xero.com/documentation/oauth2/troubleshooting. We cannot troubleshoot your settings from the Xero side as there are no tools available to us but Xero support can if you supply them with the app details you used to create it on a support ticket.
- Check with your host for any irregular server setup issues. Check your php, WordPress and Woocommerce versions are current.
The above steps will fix 99% of the connection issues. If this is not the case then there is something more in-depth. We might be able to but the investigation and work is outside of regular support. We offer it on a no-fix no-fee basis for $97 and it can be ordered from here http://www.xeroom.com/product/xeroom-after-sales-investigate-fix/ We will need an admin login and standard access to Xero as a user.
Download, Upload, Install & Activate Plugin
Download Xeroom onto your pc from the link sent when you purchased it. Then go to your WordPress plugins page and upload it. Once it says install successful then click on the activate button that will appear.
Errors – 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 you pay with Stripe. If the licence is valid you will get the success message below.
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.
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. Beware: If you have multiple people able to edit and change your Xero settings they will not automatically change in Xeroom and will need to be manually changed otherwise it will cause errors. You should prevent this by having one system owner who manages Xero, Woo and Xeroom and controls what is changed or alternatively put a formal “Change Control” process in place. 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 bookkeeper or accountant to double check these.
Sales Account – The account to which the sales are posted. Usually 200 in Xero.
Shipping/Carriage Costs – If you wish to break out this revenue then set this otherwise leave it the same as the Sales Account ie 200. It is the account that any Revenues charged to customers is posted to and is type Revenue in Xero. It is NOT the expenses account that your carriers costs are posted to. You will need to create a new one in Xero for say 210 as it is not setup by default.
Payment Methods – All the payment methods set in Woo will be listed and can be mapped into different payment accounts in Xero. Enter the Xero code for the bank or payment account which must exist and not have preceding zeros as its numbers otherwise no payments can be posted. Xero does not number these by default so you will need to edit them in Xero – set a number that makes sense to your overall chart of accounts listing eg number then 101, 102 etc or for Anzac countries is usually the 600 series eg below is an example of Anzac for the xeroom settings and UK for the Xero bank codes.
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 as many separate accounts as you want 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.
Sales Taxes Tab – Here you set the mapping of your Woo sales taxes ie VAT or GST to Xero. There are two ways to do this either simple or complex. There are mappings for Standard Rate, Reduced Rate, Zero Rate and any customer tax classes that you have set up in Woo. NB: You must enter the METHOD and NOT the account no and must EXACTLY match the spelling in Xero as found under General Settings/Tax Rates eg “20% (VAT on Expenses)”.
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 – this is a constraint of Xero and cannot be changed.
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
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.
Debug Screen – This will show your recent invoices and any associated errors that might have happened with them. Always check here first if something is not working correctly. Note: Most of these error messages are fed back from Xero which although cryptic often give meaningful clues as to what is wrong. Please always send screenshots of the debug screen when contacting Support for help.
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 corresponding 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. If it does then it is most likely a connection issue so check debug for messages to confirm this and if so try reauthorizing the connection and if that fails then create a new set of Xero keys. Common causes of this are changing your pemalinks (which is why we added the URI generation for your site) or changes in the Xero permissions of the person who created the Xero app.
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.
Why am I getting duplicate invoices in Xero?
This should not happen as we set a flag whenever an invoice is posted to prevent it being posted again accept if the Repost invoice option is used, in which case it will give it the same invoice no but with an A,B,C suffix. If you have more than one installation of Xeroom then this can cause problems with one version sending the invoice and the other sending the payment. Ensure that you only have one copy of Xeroom installed in a directory called \xeroom\ and nothing else.
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.
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.
Frequently Asked Questions
Q: Is Xeroom available as a free version?
A: No we only offer the full version under a 7-day money back guarantee. If you decide it is not for you for any reason then just email us and we will cancel your licence and refund you. We do not refund any installation services.
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 Xero account and your Woocommerce site.
Q: I already have a xero account, what do I need to do next?
A: You have to create a new application by visiting this link http://www.app.xero.com/ and follow the instructions above.