Documentation

Documentation2018-12-13T15:24:10+00:00

Woosage Overview

The Woosage Application consists of the following components:

Woosage Windows Service – this service (that can also run as a console application) runs on the same PC/Server as Sage 50 Accounts and provides the main link between WooCommerce and Sage. It runs in the background and checks to see if there are any WooCommerce orders to bring down from the website.  If not, it sleeps for a period defined in the settings. If there are orders to transfer, then they are all exported to a local database before being imported to Sage.

Woosage Desktop Client – this Windows application allows the configuration of Woosage and facilitates the inspection of the local database, which details order transfer and import status. This application is mainly for configuration, information and troubleshooting and otherwise it is not required.

A Woosage WordPress Plugin – the main purpose of the plugin is to handle the Sage Account Code in the user details, update transfer status in the Orders section of the CMS and to allow the user to force a transfer status change. If only using the default Sage Account Code, the plugin is optional.

Order Processing

Orders placed in WooCommerce will automatically transfer when the order status is PROCESSING. This state indicates that the order has been placed and paid for.

The process is initiated by the Woosage service on your local network by using the WooCommerce REST API to check the website for new orders that have not yet been transferred. When orders are transferred they are stored in a local database, which can be viewed via the Woosage Desktop Client to check the status of order imports.  After transfer orders are shown as exported on the Orders page in WooCommerce by adding a tick in the Sage Export column (see image below), if the WordPress plugin is installed.

WooCommerce Orders showing Sage Export status

The Woosage Windows Service then takes the orders from the local database and imports them to Sage.  If the import is successful it shows a Sage Reference and Processed Date in the database, which can be viewed using the Windows Desktop Client (see image below).

WooCommerce Orders showing Sage Export status

The Windows Desktop Client application does not have to be running to transfer orders, this is just a means of examining the status of orders pulled from WooCommerce and making changes to the settings.

Orders are imported to Sage as Sales Orders or Sales Invoices (defined in settings) and the order number is incremented automatically by Sage.  The WooCommerce order number is stored in the Sage Customer Order Number field as “Web Order: xxx” and is added to the first line of the Notes section of the Sage Sales Order tab in Sage, along with the currency code, as shown below. Additionally, if you are using one of the supported EU VAT plugins the validated VAT number will appear in the second line of the Notes section and any customer notes placed in the WooCommerce order will be shown on the third line.  If the customer note is more than 60 characters then its presence on the WooCommerce order is flagged here instead.  Note that the lines are not truncated and selecting each line in Sage will reveal the rest of the information.

WooCommerce Orders showing Sage Export status

Payment is not currently shown in the order and the order value is left as an amount due.  This is to avoid having to map bank accounts to currency types. A future enhancement will be to automatically update the payment details against the relevant bank accounts, based on currency.

Woosage transfers all orders in a PROCCESSING state regardless of export status.  To avoid causing transfer delays users should mark orders as COMPLETED in WooCommerce.

Common practice is for orders to be marked as COMPLETED once the order has been processed internally and the order items despatched to the customer.  This action will usually trigger an email to the customer, which may include additional information such as a tracking code.  There is an option in the Woosage settings to automatically mark orders in WooCommerce as COMPLETED once they have been successfully imported to Sage.  In some cases (e.g. virtual products that might also be posted to Sage as Sales Invoices) you may wish set this option to avoid having to manually mark it as Completed and prevent it being repeatedly exported (even though it would not get imported to Sage).  In such cases it is advisable to disable the customer email that is triggered by the process of marking as Completed.

Payment is not currently shown in the order and the order value is left as an amount due.  This is to avoid having to map bank accounts to currency types. A future enhancement will be to automatically update the payment details against the relevant bank accounts, based on currency.

Woosage transfers all orders in a PROCCESSING state regardless of export status.  To avoid causing transfer delays users should mark orders as COMPLETED in WooCommerce.

Common practice is for orders to be marked as COMPLETED once the order has been processed internally and the order items despatched to the customer.  This action will usually trigger an email to the customer, which may include additional information such as a tracking code.  There is an option in the Woosage settings to automatically mark orders in WooCommerce as COMPLETED once they have been successfully imported to Sage.  In some cases (e.g. virtual products that might also be posted to Sage as Sales Invoices) you may wish set this option to avoid having to manually mark it as Completed and prevent it being repeatedly exported (even though it would not get imported to Sage).  In such cases it is advisable to disable the customer email that is triggered by the process of marking as Completed.

Dealing with Taxes

Under normal circumstances WooCommerce uses tax classes to determine how the add tax to orders and shipping by using table of rates based on the billing or shipping address in the order (or shop base address).

Each product and the shipping classes can be assigned a tax class to determine which table of tax rates to use.  The rates are based on location (Country, State, City & Zip/Postcode) and priority (to allow application of multiple tax rates).  Each rate is given a name and this name is combined with the location elements (Country, city etc) and priority to create a tax rate code that is stored in WooCommerce orders against product and shipping (e.g. GB-VAT-1).

If no tax rate is found for a location then the tax is set to zero (0.00) and other tax-related fields are left blank (null).

It is usual to set rates for all locations you sell/ship to, applying the relevant rates.

Normally, not assigning a tax class for an item (product or shipping) or not having codes for all locations is ok, if you are happy that it does not apply any tax.  However, Sage 50 requires tax to be given tax codes (T Codes) to classify tax for various reasons (e.g. government tax returns) and Woosage uses the WooCommerce tax rate code to facilitate this via a mapping table.

We recommend that your rates include default rates (i.e. rates that apply if none of the other rates match the location information), but we have also included a default rate that will be used for mapping a T-code in such cases.

An example “Standard” tax class table might contain:

WooCommerce Orders showing Sage Export status

In the above example the first line determines that UK orders will be taxed at 20% and the second line determines that orders for everywhere else will be zero-rated (assuming all products have a “Standard” tax class).

The same would apply if the second line was omitted and although WooCommerce would still show zero tax on the order for outside the UK, this would create problems for assigning T-code in Sage.

If you use other tax classes to apply tax to product or shipping, then these work in exactly the same way and you should define tax code for each class to cover each region you sell/ship to.

All tax codes defined in WooCommerce must be mapped to a T-code un the Tax Codes tab of the Woosage Desktop Client application.

Each tax class entry that is used in WooCommerce must be mapped to an appropriate Sage tax code.  Standard, Reduced and Zero Rates are provide by WooCommerce when installed and we recommend removing tax classes that are not used.

During WooCommerce order processing a tax code is inserted in to the order.  The form of the WooCommerce tax code is Country code-Tax name-Priority (e.g. GB-VAT-1) and this is obtained by concatenating the following fields from WooCommerce/Settings/Tax/Standard Rates, Reduced Rates and Zero Rates (see image below) with a “-“ (minus) character between each:

  • Location components, such as Country code (e.g. GB)
  • Tax name (e.g. VAT)
  • Priority (e.g. 1)
WooCommerce Orders showing Sage Export status

The Sage tax codes are T0 through T99 and typical default codes are shown below, but you should check your Sage installation:

  • T0 Zero rated
  • T1 Standard Rate
  • T2 Exempt
  • T4 Sales to other EU countries (where applicable)
  • T5 Reduced
  • T9 Non-taxable

For example, VAT in the UK is typically mapped as GB-VAT-1 to T1 as indicated in the first row of the tax codes table shown below.

WooCommerce Orders showing Sage Export status

The above table must also include a default WooCommerce tax code that will be assigned to order elements that do not have tax codes.  This code does not have to exist in your WooCommerce tax class rates table and if WooCommerce has been setup correctly it should not be required.

Important Note:  Do not enable automated taxes using WooCommerce Services to automatically set tax codes as this dynamically generates names for codes based on customer location.

European Union Tax Rules for Inter-Country Sales – for Woosage users in EU countries that trade with other EU countries (regardless of whether they trade with non-EU countries) the following tax rules apply.

There is a requirement to account for and to report on inter-country sales within the EU and this is handled automatically within WooCommerce using various plugins and in Sage, by assigning the transactions with the appropriate T-codes.

Broadly, the rules for goods and services sold to a customer registered for VAT (sales tax) in another EU country are:

  • If they provide a valid VAT number (such as a VAT or TVA registration code) then the transaction is treated as zero-rated. The validated VAT number should be shown on the invoice at the sales included in the summary of sales to EU countries. Sage usually identifies this using code T4.
  • If they do not provide a valid VAT number, then you should treat the sale as though it was to a customer within your country.

Note: this is not intended to be an exhaustive explanation of EU VAT rules and we recommend taking advice from a tax specialist, particularly if you sell digital products, which are not covered here.

EU VAT numbers have the form:

CC XXX…XXX

Where:

CC is the relevant 2-character country code such as GB, FR, DE, DK etc.

XXX…XXX is the local VAT code for the organisation, which is between 8 and 12 alpha-numeric characters in length, depending on the country

If you sell to EU countries that there are several plugins that will automatically validate VAT numbers using the VIES system, store VAT numbers as evidence and zero-rate EU sales.

Woosage currently supports the following EU VAT plugins:

  • EU VAT Number – developed by WooCommerce
  • EU VAT Assistant – Developed by Aelia

If using one of these plugins, Woosage will automatically detect and deal with EU VAT by checking for the presence of a validated VAT number and zero tax.  Note that it is possible to setup the plugins to set tax to zero for a validated VAT code supplied by a customer in your own country and we recommend you do not apply such options.

In order to ensure the correct treatment of tax in Sage you must carry out the following steps:

  1. Define tax codes for the relevant classes for all EU countries set at your local tax rates.
  2. Add a tax code of EU-VAT in the Tax Codes tab of the Woosage Client Desktop application and map it to the appropriate Sage T-code (usually T4). This is set as standard in the installed database.

During WooCommerce order processing the tax will be applied by location and class and if the user provide a valid VAT code then the EU VAT plugins will store VAT numbers and set the tax to zero.  As the order is processed by Woosage the presence of the validated VAT number and zero tax will cause the EU-VAT code to be used, thereby picking up the correct T-code from the mapping table.

Note: if you use the absence of tax code to apply zero tax to product and/or shipping, then tax will not be mapped correctly in Sage.

Multi-Currency

By default, WooCommerce only operates in a single currency and Woosage will import orders in to Sage using that currency as the Sage Base Currency.

There are numerous plugins that enable WooCommerce to execute order transactions in multiple currencies.  Woosage supports the importing of sales orders in multiple currencies, with the following conditions:

  • Sage Foreign Trader option must be setup
  • Sage customer accounts that use a non-base currency must be setup to use the relevant currency
  • WooCommerce Orders must include the purchase currency (WooCommerce uses ISO currency codes)
  • Sage must use the ISO currency codes (these are used by default, but can be edited)

Sage provides a useful guide to setting up Foreign Trader at:

https://my.sage.co.uk/public/help/askarticle.aspx?articleid=26556

If the currency plugin does not populate the currency field correctly then the WooCommerce shop currency setting is likely to be used.  Details of how WooCommerce deals with currencies can be found at:

https://docs.woocommerce.com/document/shop-currency/

You can check your plugin correctly updates the order with a currency code by exporting an order and checking the currency field (order_currency), which should have the appropriate 3 character ISO code, such as USD, GBP, EUR etc.

Woosage Settings

The Woosage application settings are configured in the Woosage Desktop Client Windows application as shown below.

WooCommerce Orders showing Sage Export status

Sage Data Path – enter the directory path on the local PC/server of the Sage database

Sage Username & Password – enter the Sage logon details. These credentials should be an account specifically used for Woosage and not a user account.  Sage does not permit multiple logons to the same account.

Post Sales Invoice to Sage – By default WooCommerce orders are imported to Sage as Sales Orders. Use this toggle to import orders as Sales Invoices.

Sleep Duration – the period of time, in minutes, that the Windows Service will sleep for after checking for and transferring orders from WooCommerce. The value of this setting will depend on the volume of orders you receive and your internal order processing procedures.  During testing it is useful to set this at 1 minute, but then amend to 60 minutes.

WooCommerce URL – the full URL of the WooCommerce website

WooCommerce API Key – this is obtained from the WooCommerce settings on your website.

WooCommerce API Secret – this is obtained from the WooCommerce settings on your website.

Sage Carriage Account – Enter the Sage nominal code for your shipping or carriage costs. The default is 4095.

WooCommerce Default Tax Code – enter the WooCommerce tax code to be used in the event that an order has a missing tax code on a line item or shipping charge. This will then be mapped to the appropriate “T” code in Sage.

Sage Default Account Code – enter the Sage account that orders should be imported to if no customer specific Sage Account Code is present (or is not found in Sage). This is typically on accounts setup just for online orders rather than using specific Sage customer accounts (e.g. WEBSALES).  This account must exist on Sage.

Mark Completed in WooCommerce – by default orders that are exported to Sage are left in the Processing state. This toggle allows you to automatically   mark an order as Completed as soon as it has been exported to Sage to avoid having to manually mark it a Completed and prevent unnecessary transfer delays.

Sage Account Codes

The Woosage plugin adds a field to the website user account details (shown in the image below) to allow the Sage Account Code to be added to order generated by the user (when logged on), so that the order is imported to the relevant Sage account. If this is not present (either because it has not been setup in in the WordPress User settings, or the user did not log on) then the order will be imported to the default account.

WooCommerce Orders showing Sage Export status

The default account is configured in the Woosage application and is usually WEBSALES, WEBORDERS or similar.

User accounts must have their Sage Account Codes added manually and there is currently no facility in Woosage to auto-generate Sage Account Codes for new accounts.

If a customer Sage Account Code does not exist in Sage then default Sage Account Code will be used.  If the default code is not found then the Order will not be imported.  When setting the default account ensure it is setup correctly in Sage and matches the code in the Settings.

Sage SDO Activation

To allow Woosage to communicate with Sage an API, known as Sage Data Objects or SDO, needs to be activated within Sage, if not already activated for use with another 3rd party application.

Note: from v24.1 SDO is already activated, so it is no longer necessary to register the SDO.

If you are using an older version, then you must register the SDO using the MANAGER Sage logon credentials.

From the menu select Tools > Activation > Enable 3rd Party Integration

Enter the SDO serial number and activation key based on your version of Sage, then select Continue.

For further information about Sage SDO Activation, including Serial Numbers and Activation Keys, see:

http://ask.sage.co.uk/scripts/ask.cfg/php.exe/enduser/std_adp.php?p_faqid=9342

WooCommerce REST API setup

The WooCommerce API uses the basic authentication method using a Consumer Key and Consumer Secret that must be entered in to the Woosage settings before running Woosage for the first time.  While this method is less secure than the OAuth method it is much easier to setup as follows:

Login to your website as an Admin and select WooCommerce > Settings > Advanced > REST API.

Select Add Key and complete the Key Details:

WooCommerce Orders showing Sage Export status

Add a Description for the key and select a User that is the key owner from the drop-down.  This user must be able to access and update WooCommerce Orders.  The Permissions must be set to Read/Write.

Click the Generate API key button and the Key details window will display the Consumer Key and Consumer Secret.

Important these details will no longer be accessible once you leave this page so use the Copy buttons to save the details or paste them directly in to the Woosage settings.

Further details on the WooCommerce API can be found at:

https://docs.woocommerce.com/document/woocommerce-rest-api/

Woosage installation is simple.

First, the plugin zip file is downloaded to your local drive and added to WordPress from the CMS using Plugins>Add new>Upload Plugin.  Once installed, the plugin should be activated.  The only settings relate to the customer specific Sage Account Codes.

The Woosage Windows components are installed using the installer packaged.

VIEW PRODUCTS