Xeroom Installation and Setup Instructions


Xeroom Introduction

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.

 

Installation Overview

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 not reasonable.

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 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:

  1. Purchase, 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.
  2. 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.
  3. 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.
  4. Copy & Paste Credentials into Xeroom – Enter the two Xero app credentials from the previous step and save.
  5. 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.
  6. Configure other Xeroom settings – Add the other account, bank and sales tax settings from Xero.
  7. Check your SKU codes – Ensure that the correct codes, descriptions and prices exist in Woocommerce and Xero
  8. Test & Check Orders – Run some test purchases from your site.  Check them both in Woocommerce and in Xero.
  9. Test & Check Payments – Confirm that payments are being posted correctly.
  10. 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 along with the last few versions and release notes.

 

Connection Security – OAuth2.0 Protocol

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.

 

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 so I suggest that you use XRM as short for Xeroom instead.

Oauth 2.0 Grant Type – Auth code Web App

Company URLhttps://www.yoursite.com

Privacy Policy URL – Not used

OAuth 2.0 redirect URI – Take the URI that Xeroom has created for you based on your permalink structure and shows in the Xeroom/Settings page. (see screenshot example below).

NB: The URI Format MUST BE CORRECT TO WORK

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.

Mapping Multiple Websites to Xero – You can use the app you have just created to handle the mapping of multiple websites into your Xero account.  Simply add the new URI for the additional website into the Xero App and use the same credentials and settings in your new website.  Please order a separate Xeroom licence for the additional website.

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 to save them.

 

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 resolve this error 99% of the time.

Please check the following:

  1. Are your URI settings correct? They must be identical to that given in the bold blue line in Xeroom/settings.
  2. 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.
  3. Try deleting your Xero app and recreating it again in Xero.
  4. 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.
  5. 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 large Xero “certified” ones. Xeroom isn’t classed as “certified” as it uses Xero’s API connection, which is what they recommend for small apps.
  6. Check that the Xero permissions of the person who made the Xero App have not been changed or deleted by the Xero admin user.
  7. 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.
  8. 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.
  9. Check your firewall for possible blocks or a changed or alias URL for your website.
  10. 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.  You can pass any response onto us for assistance.
  11. 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.
  12. Check with your host for any irregular server setup issues.  Check that your php (we don’t support version 8), WordPress and Woocommerce versions are up-to-date and current.

The above steps fixes 99% of the connection issues.  If this is not the case then there is something more in-depth.   We can look into it and review what you have found – so please open a support ticket and copy the answers to the above 12 checks along with any info from Xero support, your error logs and any debug messages.

 

Xero Authentication Fails – Reconnecting to Xero

Xero Connection Broken  – If you find that when you do a test order it fails to post to Xero and you get this error message  – “Type”:null,”Title”:”Unauthorized”,”Status”:401,”Detail”:”AuthenticationUnsuccessful”  this indicates that the connection to Xero is broken due to the Xero security token failing.  You can fix it by clicking on the Authorise button in Xeroom and reconnecting.  If it is showing as connected then go to connection settings in Xero and disconnect the Xeroom app and then go back and try again to reconnect in Xeroom.

We have improved the connection stability with an automatic Xero token refresh every 15 mins in the latest version so if it is happening regularly please upgrade to the latest version  which should show in your plugins updates page or ask support for a download link (make sure you deactivate and delete your old copy first the settings will be remembered) .

 

Cause – This error most commonly happens when you – or someone in your organisation – tries to connect another app above the 2 app limit to Xero (ie 2 “unauthorised apps” which means that they are not separate SAAS platforms but accessing via the Xero API) , as it kicks out an existing app.  You can simply reconnect by clicking on Authorise in Xeroom and reselecting your Xero Xeroom app (in this case we named it Artermis XRM) to reconnect to – the status button should then go to Active, ie green and orders should then send again.  If you get a 500 cannot connect error then follow the troubleshooting above.

 

Xeroom Installation – 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.

Activation causes a critical error – In very rare situations activating Xeroom can cause generate a critical error and crash.  This is usually due to a php error or else a serious conflict with another plugin.  We do thorough testing on a number of different sites to catch most errors but can’t test for all cases and combinations of the thousands of plugins that exist.  WordPress will usually create a log of the crash so please send that to our support to look at.

Errors – If the installation and activation process causes other errors this is either due to a conflict with your other plugins or can also be a security setting in your htaccess files set usually from a security 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 and only be done by an expert as it can easily disable your site completely. It should only be done by an IT expert who knows what they are doing.

 

Activating Your 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.

NB: Due to repeated bot attacks from Russia and India we use CloudFlare to block any calls from servers with IP addresses in those countries.  If your server is located there then your licence will not activate – please email us with your server IP address to whitelist in our firewall and with our server antibot app.

Xeroom General Settings Tab

Account Selection & Validation –  When you first connect your site to your Xero account all of the accounts from your chart of accounts will be loaded into the drop-down pick lists of Xeroom.  This makes it easy to pick and set your accounts without having to keep referring back to your Chart of Accounts in Xero.  They can be refreshed by simply doing a reauthorize.  We have limited the account list to only show valid account numbers and account types for each setting thus avoiding errors in posting orders into Xero.  Also the tax settings are populated with drop-down lists of available and valid methods from Xero to pick from.  If the list is not showing then check that your connection to Xero is working by looking in the Xeroom debug screen.

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.  To be sure look in the Chart of Accounts in Xero and ask your bookkeeper or accountant to double check these.

Invoice Numbering – You can set your invoices to be created in Xero with an invoice number from a number of methods.

  1. Xero Numbering – This will just follow the Xero invoice no sequence with the next one.
  2. WooCommerce Order No –  This will use the WordPress Post ID which is usually the same as the WC order no and can be used with or without a prefix and an optional start number.  If you are not using the Post ID for the order number then you will need to use the Custom option.
  3. Custom Number – This is picking up a number to use from another plugin such as a PDF Invoice No plugin or a sequential order number plugin.  The setting here is the field used in your postmeta data table that holds the third party plugin’s invoice number.  For full details on how to find the correct setting for this please refer to this user guide.

NB: Do not use the Order No option set with a start no and no prefix since if the start number has already been used in Xero it will create a conflict with the existing numbering.

Invoice Reference Prefix – The prefix you want to be placed in the invoice reference field in Xero.  It can be:

  1. WooCommerce Order Number – to enable any orders from WC to be identified easily in Xero by the invoice users, customers or bookkeepers when doing the bank recs.
  2. Add Prefix and Gateway – This enables any reference to be prefixed and also the payment gateway that was used to be added.
  3. Custom – If the order no is set by another plugin such as PDF Invoice or Sequential Order No then tick this box and add the actual value in the box above for Custom Meta Invoice No.
  4. Reference – The last 7 digits of the payment reference can be added – again useful for bank reconciliations.
  5. Add Customer Name
  6. Purchase Order No – This enables a PO number to be used.  It is captured at checkout time using a PO gateway by this plugin https://en-nz.wordpress.org/plugins/purchase-orders-for-woocommerce/ which also has some other useful features.

 

 

 

 

 

Account Settings

Sales Account – This is the default account to which the sales are posted.  This is usually a 200 series account in Xero but will depend on your exact Chart of Accounts (COA) design.   The list is populated with all accounts of type Sales and Revenue from Xero along with Current Assets which might be used for bulk orders that are not released into the Revenue account immediately.

Shipping Revenues Account – If you wish to break out this revenue then set this to map to a different account otherwise leave it the same as the Sales Account ie 200.  This is the account that any revenues charged to customers for shipping 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.

Rounding Adjustment Account – This is the account to which any rounding adjustments are placed in Xero.  Leave blank for the default to be used.

Shipping Price Code & Description – This is to set what product code and description are used in the Xero invoice for the shipping revenues line.

Map Payment Methods to Bank Accounts – All the Payment Gateways that you have set in WooCommerce will be listed in this section and can each be individually mapped into different payment accounts in Xero.  Note that Xero does not give an account code to bank accounts by default so you will need to add them by editing them  – 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.

Clearing Accounts – Payments can also map into any clearing accounts that you use.  They can either be a  creditor/current liability type account or a bank account and can be the same one that you receive live feeds into.  If a creditor ac is used then it MUST have “Enable payments to this account” set in the settings otherwise payments sent will fail.

 

 

Benefits of adding the payments – Are that invoices get set to Paid status in Xero if an instant payment method is used eg card, Stripe or Paypal and the invoice can then be automatically emailed to the customer from Xero on checkout.  It also makes the bank reconciliations easier as automatic matching of actual payments into the bank account against the sales transactions are easier and any queries which arise especially around consolidated or bulk payments can be quickly resolved especially if the payment reference is used.

Send Payment Automatically – These tick boxes enable you to control exactly which payment methods will be sent automatically and which are not.  This works when the the Send Payments trigger is set to Automatic further down and gives a finer granularity of control.

Inventory Asset Account – The account that holds your inventory transactions in Xero. It is a special account type “inventory” The default is usually 630.  It should be present even if you are not using inventory as Xero uses it. Different groups of inventory can be given different IAA’s which is useful for reporting and knowing where the value and movements in the stock resides.

Cost of 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 – If you are going to synch your inventory then here you set where you want the inventory master to be. This setting is for an inventory check during checkout to ensure that you have sufficient stock to sell.  If you don’t then the automatic posting of the invoice will no take place since Xero will not permit the inventory to go below zero so no back orders are allowed whereas in WooCommerce they are.   Sales will affect the master directly and the resulting balance flushed to the slave as sales take place.  Inventory synch uses the SKU’s.  There is also a timed global synch of all inventory for all products on the Global Inventory Synch tab which can be almost real time ie every 5 minutes.  See below.

Product and Price Master – The products from orders on Woocommerce have SKU 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.  In some instances prices and descriptions need to be taken from those in Xero rather than WooCommerce and this provides the option to do so.

Create Invoices as Draft or 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.

Set Invoice Creation Date – This will set the date of the invoice accordingly.  If your process is to produce goods before invoicing for them then the date of posting would be better and use the Send trigger as order Completion.

Send Invoice Delivery Address – Xero has no editable fields to place the delivery address if different to the billing address.  To work around this we have provided the option to take the delivery address (when different) and post it onto the invoice as an invoice line. You do have the invoice quantity and price boxes to fill with zeros which looks a little untidy but until Xero permit custom fields this is the best we can do as it is a common requirement for many businesses that ship physical goods to have different shipping addresses.

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?

Send Credit Note Status as Draft/Approved – Set the status of your credit notes that get generated.

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.  For products this is intended for groups of products that already exist as categories in WooCommerce that can be mapped into specific Xero sales accounts. 

Note: Only the top level children of your categories are shown but will apply to all the descendants under that category.  eg clothes will take in clothes/shirts, clothes/shirts/short sleeve etc.  This mapping takes priority over the default sales account that is set above. If you wish to map sales accounts (and other attributes such as COGS) at a product level then please see Product Level Mapping below.

Make sure you create the separate accounts in Xero and then use this option to map them. 

Note: Xero doesn’t support sub-accounts so your numbering logic needs to cover for this.  It is not possible to mix and match geographies and categories.  You can have as many separate accounts as you want for each.

 

Send Invoices – Here the trigger is set to send the orders and create new invoices in Xero.  This can be manually using the button in the order or bulk send or on one of the key WooCommerce order status changes that occur in the order process.  These are on order creation, order payment (status changes to “Processing”), on hold or on completion.  Most people use On Processing ie the order is paid or intent to pay is created.

Invoice Due Date – Set the invoice due date used by Xero on the invoice.  The default is the Xero default which is 3 days.  The maximum custom setting is 30 days.

Send Payments – Set the trigger to send the payment to Xero.  They can be sent automatically (auto complete) when the order is paid for ie WC order status changes to “Processing” or manually.  Manual means using the button in the bottom right of the order or by using bulk send option on the order dashboard.  Further granularity of choice of automatic is offered by the tick boxes against each payment gateway – so some can be automatic and some not.

Note: Xeroom doesn’t complete the order in Woocommerce but leaves its status as Processing and so is really autopay.

Auto Complete implications in Xero – If payments are posted automatically to Xero once payment is confirmed  by card or PayPal it means that instead of appearing as invoices Awaiting Payment status in Xero (which can be further edited) they will appear as Paid status invoices which cannot be changed.

Tracking Categories – Set WooCommerce to use any tracking categories (2 max are allowed in Xero) that you have created in Xero eg Branch, Dept, Cost Centre. Once set here then they will appear in the product details with a selection box to set the category for each product.  The tracking categories will then appear on the invoices and be available for reporting in Xero. Separate your values by a comma.

No of Orders Sent on Bulk Request – This provides control of how many orders are sent to Xero at once.  Xero has strict limits on the amount of data and calls to the API that can be made in one go so if you find that the Bulk Send options are not working or that you have very large orders (ie larger than 10 line items per order) try reducing this.  A lower number will slow it down but avoid errors on submission to Xero and vice-versa.  The default is 4.  You can try increasing this if your invoices are small and want a faster speed of bulk send.

Xero Address Mapping – Set which address to use on the invoice.  Note if you use the Company Name and it is blank on an order then Xeroom will use the Contact Name instead which is useful if you are selling to both B2B and B2C customers.

Send Invoices – You can set your invoices to be emailed directly to your customers from Xero.  Unfortunately they cannot be sent as PDF attachments but it offers a cleaner experience for customers and is also useful for using a Payment on Account process with B2B customers – for further details see https://www.xeroom.com/payments-on-account-b2b-purchase-orders-in-woocommerce/.  If an invoice has been sent from Xero in this way then the WooCommerce Order Dashboard gets changed to a blue outline on the Xeroom Status.

 

 

 

 

 

 

Send Order Notes – It is useful to be able to show any note that the customer places on the order at checkout time onto the invoice.  Again Xero doesn’t allow custom fields on the face of the invoice so we have made a work around to show it as an item.

 

Xeroom Taxes Tab

Select Tax Methods

Here you set the mapping of all your WooCommerce sales taxes ie VAT or GST to their equivalent Xero Tax Methods.  A list of the available Tax Methods are given in the prepopulated list.  There are two ways to do this, either simple or complex. Under Simple Tax Methods there is just one mapping for each of  Standard Rate, Reduced Rate, Zero Rate and any custom tax classes that you have set up.   Under Complex Tax Methods you are given the full details of each tax type  set up in WooCommerce for each rate so exact mappings can be made.  Tax methods in Xero are found under the advanced accounting menu option.

Important: Make sure that you run tests to ensure that you have your GST/VAT tax mapping correctly set up by placing test orders for different countries and products.  Note that in WooCommerce taxes can be applied at a product level.

 

 

 

Products Inclusive/Exclusive of GST/VAT

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: 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.

Global Inventory Synch Tab

Xeroom provides the ability to synch inventory from Xero to WooCommerce or vice-versa for all tracked products on a schedule which can be daily, hourly or every 5 minutes.  This is very useful if you are operating a physical shop with transactions going directly into Xero via a Point of Sale system that is decrementing inventory in real-time.  Synchronizing the inventory into WooCommerce means that your online store is always up-to-date with inventory.  Alternatively your physical shop may be only a small part of your business or open for short periods in which case you can make WooCommerce your inventory master.  You can use this global synch in tandem with the individual product synch that occurs during checkout to give flexibility about how you manage your stock.   For example the global synch could be Xero to WooCommerce and the checkout check is the other way to say facilitate back orders.  Or you might have two online stores synching to the same Xero account.

Synch all products – Select which direction you want the synch to flow in.

Batch size – Xero strictly controls the no of API calls and rate so the synch data needs to be throttled to a rate that doesn’t risk breaching this.  You can set up to 500 for the batch size and your products will be chunked in batches of 500.  If you encounter issues with the synch not happening correctly then scale this back to 250 or 100 for the chunk batch size.

Synch Now – This enables you to test the synch is working properly.  The synch process runs a small cron job.  Click the button twice as sometimes the job doesn’t run.

Log File – After synch an Excel log file is generated which shows the results of the synch.  Check this file when testing to ensure no errors are occuring.

Errors – If the synch is not working then check the Xeroom Debug screen, your WooCommerce error log and that your cron jobs are running ok.

Global Product Synch Tab

This tab enables all your products to be synched into Xero from WooCommerce and run on an automated schedule. 

NB: VERY IMPORTANT – Use this option with great caution and at your own risk as it will overwrite your existing Xero product data and Xero has no backups.  Ensure that you know what you are doing and test first with a Xero demo account before attempting to use on your live Xero account.

Product Level Attributes for Xero

Products can now be mapped into Xero at an individual product level of granularity.   The key accounts that are used for a product in Xero can be set here in WooCommerce under the Product data where you will find a new tab Xero Account Settings.  The setting is placed here to avoid poor performance when sending the data during checkout.  The pick lists are all prepopulated with the account and descriptions however for a bulk load it is much more efficient to upload from a spreadsheet using a tool such as All-in-one-import plugin.  

 

Tracking Category (example Brands) – Here the tracking categories that have been set up in Xero can be assigned to products.

Sales Account – Any setting here takes priority over the other sales account settings ie Product level > Product Category > General Xeroom Setting.

Cost of Goods Sold Account – Any setting here takes priority over the General Xeroom Setting for COGS account.

Inventory Asset Account – Any setting here takes priority over the General Xeroom Setting for Inventory Asset Account.  The IAA tracks all the movements and transactions involving inventory and multiple IAA’s can be used to cover different classes or groups of products.   

NB Important limitation: Once an IAA has been set to a product in Xero it becomes fixed and cannot be changed so Xeroom is not able to overwrite existing values in Xero with a different value from here.  ie any existing tracked products in Xero MUST have matching IAA account values set in this tab.  Furthermore no validation is performed by Xeroom to check if the IAA has already been set for a product or not.

lnvoice Status Synch Tab

(Synch Xero payments back to WooCommerce)

When an invoice has been created in Xero by Xeroom and is then paid off in Xero, eg at month end for payments on account customers,  then the payment can be synched back to the order in WooCommerce using this feature.  The orders are then shown in blue on the order dashboard as Paid in Xero status.

For instructions on how to set this up please go to setting up payments synch.

Testing Your Integration

Test and Check Order Sending

Important: Once you have completed the setup and configuration run some test purchases from your site.  Try to cover a number of scenarios and processes eg placing an order from an overseas country and checking the invoice results are correct.  Check them both in Woocommerce in the orders dashboard and in Xero.  A typical invoice of would look like below.  If you encounter any issues then please look at the errors shown on the Xeroom Debug screen.  This feeds back any error messages from Xero so it is the first place to look for things not being correct.  The next place to check is your WooCommerce error log for any errors with the word “xeroom” in.  This requires turning on – for details please see our Support page and section 6 explains how to do this https://www.xeroom.com/support/.  If you are not able to resolve any errors found then please open a ticket by emailing [email protected] with copies of your debug screen and any error log.

 

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 Sending

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 showing the full address and no Xeroom reference.

Testing of Manual Posting of Of Orders and 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.

Testing Refunds & Generation of 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.

Common 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 your Xero connection – check the Debug screen in Xeroom.

Debug ScreenThis will show your recent invoices and any associated errors that might have happened with them. It will also show if the order posting was successful or note.  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?

Orders are posted to Xero depending on the trigger set as described above. For immediate sending the triggers start 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 sent either manually or automatically as covered above.  The automatic trigger sends to Xero when the payment is complete either by an instant method such as card or PayPal or when a Bank Transfer occurs.  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 is 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 WooCommerce is not communicating with Xero due to the Xero API keys being wrong or expired or the security token needs resetting by a reauthorisation of the Xero app.

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 SKU 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 revenue 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 an API connection 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.