WooCommerce: integration guide
About this document
This document describes ChannelEngine's WooCommerce plugin, how to install it, how to configure it, and more.
Table of contents
WooCommerce is an extension of WordPress, which is a content management system (CMS). While WooCommerce can add some basic ecommerce options to a website, it is not a full ecommerce platform. This is why features such as returns are not supported within WooCommerce.
|Product data (via product feed)||External fulfillment orders|
|Shipments||Order extra information/data|
The only one requirement to install the WooCommerce plugin is WordPress 4.9 (or higher).
ChannelEngine's WooCommerce plugin is offered via the official WooCommerce plugin manager. To install it, do the following:
- Log into the WordPress back-end
- Open the plugin page and select Add new
- Use the Search plugins field to find ChannelEngine
- Select WooCommerce ChannelEngine to install it
It is also possible to install the plugin from the WordPress website.
If needed, the source code for the plugin can be found on ChannelEngine's GitHub.
- The plugin can be configured by selecting Settings on the WordPress plugin list.
- Add the required credentials, such as the account name and API key.
- The account name is the subdomain for your channelengine.net environment (e.g.: woocommerce-test).
- The API key can be managed from the ChannelEngine web interface under Settings > Merchant API key.
- From this page, you can create new API keys or copy an existing one for use on WooCommerce. It is recommended to create a separate key for WooCommerce. The API key needs to be copied into WooCommerce's General settings (as shown in step 2).
- Note that in earlier versions of the plugin, the API secret key was also required. Although this is no longer the case, the latest version of the plugin still has a validation for this field. You can ignore the Invalid credentials warning.
To import your product data from WooCommerce to ChannelEngine, you need to import the product feed from the WooCommerce plugin to ChannelEngine.
- Go to the ChannelEngine plugin settings on WooCommerce, under WooCommerce > ChannelEngine.
- Copy the URL as shown in Product feed URL.
- On ChannelEngine, go to Products > Product feeds and select + Add feed.
- Paste the URL of the WooCommerce product feed into the input field and select Load product feed.
- You are then prompted to select the 'node' for the product information, which is Products.
- Select Continue.
- In the feed mapping overview, you can map all the data attributes from the product feed to attributes on ChannelEngine. For more information on feed mapping and how it is set up, check out Product feeds.
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', have no commas 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, check if you have these filled in on WooCommerce. To do so, go to WooCommerce > Products > Product data > ChannelEngine (as in the image below). The GTIN (EAN) is particularly important, but sizes, color, and shipping information are also essential for many channels.
- If you have custom attributes for products on WooCommerce, they should be available under Products --> Specs.
- Once you save the settings, the import task is automatically scheduled. Your products appear in your ChannelEngine account once the Import product data from merchant task is completed. This usually takes a few minutes.
An improved way of handling orders is currently under development. If you need assistance with this in the meantime, please contact your Onboarding Specialist.
Once you have installed and configured the plugin, and added and imported the feed on ChannelEngine, contact your Integration Coordinator, Customer Success Manager or the Support team.
They verify your installation by checking if the notification URL can be used for retrieving orders. If no orders exist, either you or ChannelEngine can create a test order. If all is well, they can add a task to the schedule which calls the order webhook every 15-30 minutes to make WooCommerce fetch orders.
You can then start using ChannelEngine and adding more channels.
The product data comes from the product feed, as generated on WooCommerce. This feed also contains the product stock.
By default, ChannelEngine imports it hourly, but it is possible to have this done every 30 minutes if needed. Bear in mind that the feed is generated the moment the URL is called, which causes some load on your web server because it fetches all the products and their data. This is why ChannelEngine discourages calling the feed more than once every 30 minutes.
ChannelEngine strongly discourages disabling stock reservations when using WooCommerce, as stock updates have a delay and out-of-stock orders might occur often – especially when connected to multiple marketplaces. More information on stock can be found on Stock.
New orders from ChannelEngine appear in the WooCommerce > Orders overview.
On orders coming from ChannelEngine to WooCommerce:
- Orders are created as a 'guest', as it is not possible to create and reuse a customer for every order.
- The channel name and order number cannot be seen in the Orders overview, and they cannot be used as a search parameter either. If you need to find a specific order, you are advised to look up the order on ChannelEngine.
There you can see the Merchant order number. This number matches the ID of the order on WooCommerce. In the example above, Merchant order number 55 can be used to find the related order on WooCommerce.
Orders do not contain any order extra data, like some marketplaces do.
WooCommerce lacks support for shipments, cancelations, and returns (at least as separate entities). Except for returns, these operations are possible but are limited in comparison with other platforms.
Shipments are supported by WooCommerce, but are not exported to ChannelEngine unless submitted via a specific way and process. To submit a shipment to ChannelEngine, do the following:
- Edit the order's shipping address.
- Add the track-and-trace code and the shipping method (carrier) to the corresponding fields.
Update the order status to Completed.
Update the order by selecting Update in the top right corner.
This triggers an API call to ChannelEngine's API, creating a shipment on ChannelEngine. This, in turn, is exported to the channel.
More on shipments
- It is not possible to partially ship items. Shipment created in this way apply to all items in the order.
- If you want to automate the addition of the track-and-trace information to orders, make sure these two fields are filled in and that you do not change the status of the order to Completed before this is done.
Cancelations are supported by WooCommerce. To submit a cancelation to ChannelEngine (please be aware that a 'partial' cancellation of a single order line in case of multiple order lines, is not possible), set the status of an order to Cancelled and update the order status.
This triggers an API call to ChannelEngine's API, creating a cancelation on ChannelEngine. This, in turn, is exported to the channel.
Returns are currently not supported. If this is a priority feature for you, please contact your Customer Success Manager as they can give more priority to features if popular demand warrants that.
ChannelEngine's advice is to use the ChannelEngine web interface to create and handle returns.
- My product feed is not generated or it is empty. What should I do?
- I am using the latest version of the Mollie plugin together with the ChannelEngine plugin, and this is returning errors.
- Can ChannelEngine automatically add the track-and-trace information from my carrier's fulfillment plugin?
This is usually caused by a timeout during the generation of the product feed. 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.
It is also possible that not enough write permissions were given. Make sure that there are sufficient rights to write data to the ChannelEngine folder.
Whatever the reason, you should 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. E.g.: the default location for an Apache web server is /var/log/apache2/error.log.
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 uses a newer version of GuzzleHttp than ChannelEngine, which causes errors because they are not compatible. The upgrade to a newer version is planned, however, there are a lot of linked dependencies so this is a multi-stage process.
In the meantime, you can use an older version of the Mollie plugin (the latest supoorted version is 5.3.2) if you want to use ChannelEngine and Mollie together.
While this is possible for other types of webshop software (such as Magento, which has a separate section for shipments), it 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 WooCommerce generic input fields and a specific trigger to create a shipment, ChannelEngine can only offer the manual option to add information.
However, if you incorporate some code into your fulfillment plugin or WooCommerce's environment, you can trigger shipments to ChannelEngine. The following code is used for storing the track-and-trace information on WooCommerce:
update_post_meta($wc_order->get_id(), '_shipping_ce_track_and_trace', '3S1234ABCD')
If you store the relevant track-and-trace number in the _shipping_ce_track_and_trace metafield, it should trigger an export of a shipment to ChannelEngine.