WooCommerce integration guide

// Contents

Introduction
Woocommerce Integration features
Installation requirements
Installing the extension
Configuring the plugin
Link product data to ChannelEngine
Getting orders from ChannelEngine
Activate your connection
Product data/stock
Orders
Shipments, cancellations & returns
Troubleshooting issues & frequently asked questions

// Introduction

To connect your WooCommerce webshop to ChannelEngine, you are required to install our WooCommerce extension. This guide will explain how to install and configure the plugin. 

Please be aware that WooCommerce is an extension of WordPress which in its core functionality is still blogging software. While WooCommerce adds some basic e-commerce / webshop options to a website, it is not a full e-commerce platform supporting all possible facets. This is why operations like returns are not possible when using WooCommerce.

// WooCommerce integration features

Supported Not supported
Product data (via product feed) External fulfillment orders
Orders Returns
Shipments Order extra information / data
Cancellations

// Requirements

There is only one requirement to install the WooCommerce extension:

  • Requires: WordPress 4.9 or higher

// Installing the extension

Our WooCommerce extension is offered via the official WooCommerce plugin manager. Installing and updating the extension using WordPress is easy. The installation is started by logging in in the WordPress Admin, opening the plugin page and press “Add new”. Use the “search plugins” box to find ChannelEngine, a “WooCommerce ChannelEngine” plugin will appear, which can be installed directly. It is also possible to install the plugin from  the WordPress website.

If desired, the source code for the plugin can also be found on GitHub.

// Configuration

  1. The plugin can be configured by pressing the “settings” button (Figure 1) in the WordPress plugin list.
    Figure 1: The WordPress plugin list
  2. This opens the configuration (Figure 2) where the credentials such as account name & API key should be filled in. 
  3. The account name is the subdomain for your channelengine.net environment (so woocommerce-test for example).
    Figure 2: The ChannelEngine plugin settings
    Please note: Your account name is the subdomain for your account, which is not necessarily the same as the name of your account itself! 
    So if your account has the name 'WooCommerce test' and the subdomain is woocommerce-test.channelengine.net, woocommerce-test is what you enter as the account name in the settings in WooCommerce.
  4. The API-key can be managed from the ChannelEngine webinterface on the Settings > Merchant API keys page.
    Figure 3: The Merchant API key management in ChannelEngine
  5. From this page, you can create new API keys or copy an existing one for use in WooCommerce. We recommend creating a separate key for WooCommerce. The API Key(Figure 4) needs to be copied into the WooCommerce plugin general settings as shown in step 2.
    Figure 4: Enter the correct API key in WooCommerce
  6. Please note: in earlier versions of the plugin, the ‘API Secret Key‘ was also required. This is no longer the case. However, the latest version of the plugin still has a validation for this field. You can ignore the warning "Invalid credentials"; the plugin will work fine without the API Secret Key.
    Figure 5: Warning that can be ignored!

// Link product data to ChannelEngine

To get your product data from Woocommerce to ChannelEngine, you will need to add the product feed from the WooCommerce plugin to ChannelEngine and set it up. To go into details step by step:

  1. First, if you are not there already, go back to the ChannelEngine plugin settings in WooCommerce (WooCommerce > ChannelEngine).
  2. Copy the URL as shown in Product feed URL.
  3. In ChannelEngine, navigate to Products > Product feeds and press the blue + Add feed button to add the product feed.

  4. Paste the URL of the woocommerce product feed in the input field and press the 'Load product feed' button.
  5. You'll now be prompted to select the "node" for the product information. This will be Products.

  6. Press the Continue button.
  7. You'll see the feed mapping overview now, where you can map all the data attributes from the product feed to attributes in ChannelEngine. More generic information on ‘feed mapping’ and how this needs to be set up can be found here.

    / Some important information regarding mapping WooCommerce attributes:

    • Leave all the settings as shown as feed options on the top of the feed mapping screen as they are. The feed should be 'Leading', has no comma's as decimal separator and no parents or grandparents should be generated.
    • If your GTIN, Color and Brand fields are empty for the examples that are shown in the feed mapping, please check if you have these filled in WooCommerce. To do so, go to WooCommerce > Products > Product data > ChannelEngine (as in the image below). Especially the GTIN (EAN) is important, but sizes, color, and shipping information are also essential for a lot of channels.
    • If you have custom attributes for products in WooCommerce, they should be available in the Products --> Specs section of your feed.
  8. After saving the settings the import task will automatically be scheduled. Your products will appear in your ChannelEngine account once the 'Import product data from merchant' task is completed for your feed (this will usually be within minutes).

// Getting orders from ChannelEngine

To get the marketplace orders in your WooCommerce environment, our system will call a webhook in WooCommerce, triggering WooCommerce to fetch and process orders via our merchant API. To set this up:

  1. First, fill in the ‘notification URL’ (Figure 3) in your ChannelEngine account. This field can be found on the Settings Settings page in ChannelEngine in the API settings section.
  2. This notification URL always consists of https://[ TheUrlOfYourShop]/ChannelEngine/callback. Replace ‘[TheUrlOfYourShop]’ with the domain name your WooCommerce shop uses. In our example this is woocommerce.channelengine.com, but if your webshop is awesomewebshop.co.uk, then your callback URL will most likely be https://awesomewebshop.co.uk/ChannelEngine/callback.
  3. In order for this to properly work, please be aware of the following:
    • Please do not cache anything in the /ChannelEngine folder (so exclude it from caching). If you do cache this folder, the product data will be outdated (including your stock) and the order webhook will not fetch new orders (because cached content is triggered) for as long as the previous data is cached.
    • If you use some form of IP whitelisting on some parts of your WooCommerce environment, please make sure to whitelist ChannelEngine's IP's.
    • WooCommerce only accepts known SKU's / Ids for orders. If you have any old offers with other SKU's online, please be aware that WooCommerce will not accept them and those orders will always remain on 'New'. Also, see https://help.channelengine.com/article/134-why-are-my-orders-not-being-imported#woocommerce for more possible reasons why WooCommerce does not fetch an order.
    • On ChannelEngine's side, a (scheduled) task should be added that calls the order webhook every x minutes. If you never see a task labeled 'Call order webhook at merchant' in your scheduled tasks, please contact ChannelEngine to have this double-checked and fixed (also see activate your connection).

// Activate your connection

After you've set up all the necessary steps as listed above (installing and configuring the plugin, adding and importing the feed in ChannelEngine), please contact your integration coordinator or customer success manager, or mail to support@channelengine.com

We will then verify your installation by checking if the notification URL can be used for retrieving orders (if no orders exist, you or ChannelEngine can always create a test order to test with). If this is the case, we will add a task to the schedule which will call the order webhook every 15-30 minutes to make WooCommerce fetch orders.

After which you can start using ChannelEngine and adding more channels.

// Product data/stock

As may already be apparent from the section about linking product data to ChannelEngine, product data comes from the product feed as generated in WooCommerce. This feed will also contain the product stock.

By default, we will import it once an hour, but it is possible to have this changed to once every 30 minutes if desired. Please be aware that the feed will be generated at the moment the URL is called, and this will always cause some load on your web server because it will fetch all the products and their data. This is why we discourage calling the feed more than once every 30 minutes.

When using WooCommerce, we strongly discourage disabling stock reservations as stock updates will have a delay and out-of-stock orders (especially when connected to multiple marketplaces) might occur often. More information on stock can be found here.

// Orders

New orders from ChannelEngine will appear in the regular WooCommerce > Orders overview.

/ Some information regarding orders coming from ChannelEngine to WooCommerce:

  • Orders will always be created as a 'Guest' as it's not possible to create (and re-use) a customer for every order.
  • In the Order overview you can not see the marketplace (channel) name or order number. They can not be used as a search parameter either. Should you wish to find a specific order, you are advised to look up the order in ChannelEngine.

    There you will see the Merchant order no. This number matches the id of the order in WooCommerce, so with the '55' from our example you are able to find the order in WooCommerce.

  • Orders will not contain any 'order extra data' like some marketplaces (for example Amazon) has.

// Shipments, cancellations & returns

While WooCommerce adds some e-commerce functionality to WordPress, like the option to create and process orders, it is lacking support for shipments, cancellations and returns (at least as separate entities). Therefore these type of operations are possible (with the exception of returns), but are limited in comparison to other webshop platforms.

/ Shipments

Shipments are possible for WooCommerce, but will not get to ChannelEngine unless submitted via a specific way and process. To submit a shipment to ChannelEngine:

  1. Edit the Shipping address on the Order.
  2. Add the Track & Trace number and the Method (Carrier) to the corresponding fields.

  3. Now update the status to Completed.

  4. Now update the order by pressing the Update button in the top right corner.

  5. This will trigger an API call to our API creating a shipment in ChannelEngine. That, in turn, will be exported to the marketplace.

Some important information regarding shipments

  • It's not possible to partially ship items. You can only create one shipment this way for all items in the order.
  • If you want to automate adding the track & trace information to orders, please make sure these 2 fields are filled AND that you do not change the status of the order to 'Completed' before this has occurred.

/ Cancellations

Cancellations are possible for WooCommerce. To submit a cancellation to ChannelEngine (please be aware that a 'partial' cancellation of a single order line in case of multiple order lines, is not possible), you need to set the status of an order to ' Cancelled' and Update the order status.

This will trigger an API call to our API creating a cancellation in ChannelEngine. That, in turn, will be exported to the marketplace.

/ Returns

Returns are currently not available within WooCommerce. While it would technically be possible to create a plugin that would add this, this would require a lot of work and maintenance and this is currently not where ChannelEngine's development focus lies. Should having full returns support on WooCommerce really be a priority feature for you, please contact your customer success manager as they can give features more priority if popular demand warrants that.

Our advice is to use the ChannelEngine web interface for creating and handling returns at this time.

// Troubleshooting & frequently asked questions

  • My product feed isn't generated/is empty

    This is usually due to a timeout during the generation of the product feed. Please note that if you have a shared hosting web server (with strict limits) and a lot of products, the generation of the product feed may time out causing the feed to be empty or only partially generated. Please contact you hosting company 

    A different reason the feed isn't generated could also be that there aren't sufficient rights to write data. Make sure that there are sufficient rights to write data to the ChannelEngine folder.

    Whatever the reason, you should always be able to find it in the error log of your webserver. Depending on your host, the used webserver and configuration, the exact location can vary (the default location for an Apache web server is /var/log/apache2/error.log for example).
  • I'm using the latest version of the Mollie plugin together with the ChannelEngine plugin and this is giving errors

    This is unfortunately correct. The cause for this issue lies in that both the Mollie plugin and the ChannelEngine plugin use a certain dependency on external code (in this case the GuzzleHttp client). The newest version of the Mollie plugin use a newer version of GuzzleHttp than ChannelEngine and this causes errors because these are not compatible. We are planning on upgrading to a newer version as well, however, there are a lot of linked dependencies so this is a multi-stage process. 

    Until we have updated our GuzzleHttp client version and a new WooCommerce plugin, the only solution is to use an older version of the Mollie plugin (the latest possible version is 5.3.2) if you want to use both that and ChannelEngine together.
  • Can't you automatically add the T&T-information from my carrier's fulfillment plugin?

    While this is perfectly possible for other types of webshop software like Magento, which have a separate section for shipments, this is not possible for WooCommerce. Most fulfillment plugins only add a comment to an order with some information about the shipment, but nothing in a fixed format that can be used across all fulfillment providers / carriers and offer a one-size-fits-all solution. Without having WooCommerce generic input fields and a specific 'trigger' to create a shipment, we can only offer the manual option for adding information like the plugin does now.

    However, if you have the ability to incorporate some code somewhere into your fulfillment plugin or WooCommerce environment, you can trigger shipments to ChannelEngine. The following code is used for storing the track & trace information in WooCommerce:
    update_post_meta($wc_order->get_id(), '_shipping_ce_track_and_trace', '3S1234ABCD')	

    If you are able to store the relevant track & trace number in the _shipping_ce_track_and_trace meta field, it should trigger an export of a shipment to ChannelEngine.