WooCommerce: integration guide
About this guide
This guide describes ChannelEngine's integration with WooCommerce, including how to install and configure the connector, and more.
Table of contents
WooCommerce is an ecommerce extension of WordPress, which is a content management system (CMS). It is designed to help small to medium-sized merchants create and customize ecommerce stores, turning a regular website into a fully functioning online store.
The latest version of the WooCommerce plugin for ChannelEngine works via the Merchant API, as opposed to the previous version of the integration which worked via product feeds. This plugin, therefore, provides support for some additional functionalities, and the entire configuration process happens through the WooCommerce interface – including attribute and order status mapping.
|Product data||Order extra information/data|
|Orders||Multiple stock locations|
|Shipments||Three-level product structure|
|Cancelations||Third-party shipping plugins**|
|External fulfillment orders|
* Returns are not supported by this plugin. WooCommerce supports various third-party plugins, which provide returns functionality on the WooCommerce App Marketplace.
** While it is possible to use third-party shipping plugins with this integration, it requires additional development on your side.
This plugin supports WooCommerce versions 3.7 (running on PHP 5.6), 5.4 (running PHP 7.4), and 6.8 (running on 8.1).
You need to have WordPress/WooCommerce login credentials to access WooCommerce and configure the plugin.
Install the connector
The latest version of the WooCommerce connector is available for download from ChannelEngine. Contact ChannelEngine's Support team to request access to the connector, then follow the instructions below to install the ZIP file in your WooCommerce environment.
- Log in to your WordPress back-end.
- Go to Plugins, Add new, and click Upload plugin.
- Click Browse, locate the ZIP file for the plugin, then click Select to upload it.
- Click Install now.
Activate the connector
Once the connector is successfully installed, it needs to be activated before configuration can take place. This can be done immediately upon installation by clicking Activate on the landing page. To complete activation at a later stage, go to Plugins, Installed plugins from the sidebar, and click Activate under the latest version of the ChannelEngine connector.
Configuration of the connector can take place when it is both installed and activated.
Connect with ChannelEngine
- Open the ChannelEngine connector on WooCommerce via one of two methods:
- The first time you open the connector, a 'Welcome to ChannelEngine' page is displayed. Click the Configure button to begin the configuration process.
Enter your ChannelEngine account name and API key into the relevant fields, then click Connect and continue.
The second step of the configuration process allows you to enable or disable stock synchronization between WooCommerce and ChannelEngine.
If enabled, you can use the option to Set the default stock quantity for products that do not have a stock quantity already configured on WooCommerce. This allows ChannelEngine to import products even if there is no stock information available on WooCommerce, but the stock is automatically set to the quantity you define here. Note that this is a global setting that cannot be applied on a product-by-product basis. The recommended default quantity is 0 (zero) units.
During this step, you can make changes to the way product attributes are mapped between WooCommerce and ChannelEngine. Select an attribute from the dropdown menu to map a WooCommerce attribute to the ChannelEngine attribute (e.g.: mapping the ChannelEngine attribute GTIN to the WooCommerce attribute EAN). You can also leave attributes unmapped if desired by selecting Not mapped.
To map custom product fields, select the option Extra data mapping.
Click Save and continue to proceed to the next configuration step.
During this step, you can map your WooCommerce order statuses to ChannelEngine order statuses, and configure how orders are synchronized.
- Automatically reduce the stock - if this option is enabled, product stock is updated when a new order is imported to WooCommerce.
Order synchronization - choose which synchronization to apply for the following options. You may opt to disable any of the below options based on whether your orders/shipments are handled solely by an external system, such as your enterprise resource planning (ERP) system, or, if you do not wish to use the WooCommerce system, to synchronize order/shipment data.
- Shipments - enable synchronization of shipment information.
- Cancelations - enable synchronization of order cancelations.
- Order fulfilled by the merchant - if enabled, orders to be fulfilled by the merchant and with the status New are imported by WooCommerce.
Order fulfilled by the marketplace - if enabled, marketplace-fulfilled orders are imported by WooCommerce from the date you enter into the date field. This field is handy to specify from which point you want to import old orders, so you can avoid flooding your database with hundreds or thousands of orders from years prior. Note: this date can only be set once, so be sure to input the correct date during configuration.
Order status mapping - map WooCommerce order statuses to ChannelEngine statuses. I.e.: Pending payment, Processing, On hold, Completed, Canceled, Refunded, and Failed.
- Status of incoming orders - select the status you want to map to orders which have yet to be processed. E.g.: Processing.
- Status that defines a shipped order - select the status you want to map to orders that are shipped. The status you select determines the point at which ChannelEngine creates an automated shipment. E.g.: Completed. For more information on how this setting determines when ChannelEngine creates shipments for closed orders, see the below section on Shipments.
- Status of orders fulfilled by a marketplace - select the status you want to map to orders that are fulfilled by a marketplace. E.g.: Completed.
- Click Save and continue to save your current order synchronization configuration.
The final configuration step is to enable the integration and begin the first synchronization task between WooCommerce and ChannelEngine. Click Enable and start sync to begin transferring products from your published WooCommerce store to ChannelEngine, and to fetch orders from ChannelEngine into WooCommerce.
Live product synchronization
After the initial synchronization, the integration synchronizes product information between WooCommerce and ChannelEngine as follows:
- Newly created products in the store are automatically created on ChannelEngine.
- Updated products in the store are automatically updated on ChannelEngine.
- Deleted products in the store are automatically deleted from ChannelEngine.
After the initial synchronization, all new orders are automatically pushed from ChannelEngine to your WooCommerce store. They appear in the Order overview on WooCommerce.
The order on WooCommerce is given an Order ID that matches the Merchant order number on ChannelEngine.
Orders on WooCommerce are considered shipped on ChannelEngine when the order status matches the one you configured during the Order status mapping step. E.g.: if you set the Status that defines a shipped order to Completed, then orders are considered 'shipped' by ChannelEngine when the order status is Completed. A shipment is then automatically created for the order on ChannelEngine.
Following the successful creation of a shipment on ChannelEngine, a notification is displayed at the top of the Edit order page on WooCommerce.
Retrieve tracking codes
Tracking codes can be retrieved using the following WooCommerce function, where $postID represents the order ID.
get_post_meta( $postID, 'ce_tracking_code', true )
Save tracking codes on ChannelEngine
Tracking codes can be saved on ChannelEngine using the following WooCommerce function, where $postID represents the order ID and $trackAndTrace represents the desired tracking code.
update_post_meta( $postID, '_shipping_ce_track_and_trace', $trackAndTrace )
Update tracking codes on ChannelEngine
Tracking codes can be updated on ChannelEngine by calling the save function of the controller
ChannelEngine\Controllers\Channel_Engine_Order_Overview_Controller. The relevant file is:
This function is an open endpoint, which can be called:
All three parameters are required, which means you also need to set the shipping method. The value for the shipping method can be found by inspecting the Track & trace dropdown menu on WooCommerce’s order detail page.
Update tracking codes on WooCommerce
All orders pushed to WooCommerce display information fetched from ChannelEngine on the Edit order page on WooCommerce. From this information box, you can choose a shipping method and enter tracking codes for shipped orders.
Click Update tracking information to synchronize the updated tracking information with ChannelEngine. If an order is not yet shipped, the tracking code is saved locally – and synchronized with ChannelEngine when the order is shipped.
Updating the status of the order to match the Status that defines a shipped order (e.g.: Completed) and saving triggers the shipment to be created on ChannelEngine.
For products with variations (parent-child relationships), you can set a product image on WooCommerce. For more information, see WooCommerce's Adding product images and galleries guide.
These images are imported as the main image for the parent product on ChannelEngine.
To assign an image per product variation (child), select Variations in the product data menu on WooCommerce under WooCommerce, Products.
Images you upload here are imported into ChannelEngine as the main image for the child product. If no image is provided for the variation, then the image you uploaded for the parent product is used.
Note that images added to the product gallery on WooCommerce are added to all parent and child products on ChannelEngine.
Product gallery on WooCommerce
Images on ChannelEngine
For more information about product creation, refer to WooCommerce's Adding and managing products guide.
For cancelations to be synchronized between WooCommerce and ChannelEngine, you must have enabled the Order cancelation synchronization option during the configuration process.
If you cancel an order that was imported from ChannelEngine, the status change is communicated back to ChannelEngine. A notification is then displayed at the top of the Edit order page on WooCommerce to indicate that the synchronization was successful.
It is not possible to edit tracking codes for canceled orders, but the information that was imported from ChannelEngine remains visible for these orders.
How can I see if my synchronization tasks were successful, or see error messages for failed tasks?
For every background synchronization task performed by the ChannelEngine plugin (e.g.: product and order synchronization, unsuccessful API calls, etc.), an entry is made in the transaction log. Every task is stored in this history log, alongside a message indicating whether or not the task was successful.
To access the transaction log, go to WooCommerce, ChannelEngine, and click the Transaction log tab.
How can I solve the error 'libcurl error code 51'?
Unable to communicate securely with peer: requested domain name does not match the server's certificate.
This error can occur if the account name in the WooCommerce plugin is not correct. To solve it, go to the Dashboard of the ChannelEngine plugin on WooCommerce and ensure that the correct subdomain name for your ChannelEngine environment is entered into the Account name field.
During installation the synchronization did not complete - what do I do?
We recommend deleting and reinstalling the WooCommerce plugin.
How can I delete and reinstall the plugin?
Go to WooCommerce, Installed plugins, and deactivate the ChannelEngine plugin. once deactivated, the option to delete the plugin then becomes available.