Adobe Commerce 3.0: merchant plugin guide

About this guide

This guide describes ChannelEngine's integration with Adobe Commerce 3.0, including how to install and configure it.

Table of contents

Introduction

Plugin features

Requirements

How to request an account

Download the plugin

Connect the plugin with ChannelEngine

• Installation
• Setup
• Activation

Overview

FAQs

Introduction

Adobe Commerce is a leading ecommerce platform that offers webstore functionality. The platform is designed to help merchants personalize the look, content, and functionality of their store.

ChannelEngine's Adobe Commerce 3.0 plugin is intended for medium to large businesses, including enterprise users. The plugin fully relies on Adobe Commerce API, which helps prevent conflicts with existing plugins and customizations in your Adobe Commerce environment. The Adobe Commerce merchant plugin comes with built-in features and fully open-source code that you can customize as needed.

Plugin features

1. In Setup, if you select the MPN alias as the Product ID, the three-level product structure is no longer supported.
2. Both merchant and marketplace returns are only supported by Adobe Commerce Cloud/Enterprise Edition. Marketplace-fulfilled returns, e.g.: FBA, ZFS, LVB, are not supported.
3. You can configure return tracking codes on Adobe Commerce 3.0 using the additional tracking number. To learn more, check out the article Adobe Commerce 3.0: return tracking code.

Requirements

To install ChannelEngine's Adobe Commerce plugin, you must meet the following requirements:

• Adobe Commerce 2.0 or higher (Open Source, Commerce, Cloud)*
• Access to the Adobe Commerce admin

* Adobe Commerce 2.4 or higher is recommended.

How to request an account

To sign up for an account on Adobe Commerce, visit Adobe's website and request a product demo.

Download the plugin

You can find the Adobe Commerce plugin in its various forms on ChannelEngine: webstore integrations. Select the package or method you want to use and download it.

For a guide on how to install the Adobe Commerce plugin as a zip file, check out How to install modules manually in Magento 2 article.

Connect the plugin with ChannelEngine

Installation

ChannelEngine's Adobe Commerce plugin uses the new Adobe Commerce integrations feature. This makes integrating with ChannelEngine both easier and faster.

1. Install the Adobe Commerce plugin via composer or the web installer. For composer, see Manage third-party extensions in the Adobe Commerce Installation Guide and follow these instructions:

   • Modify the composer.json to make sure that updates to the magento2 module from non-marketplace repositories take precedence:

     "repositories": [
        {
            "type": "composer",
            "url": "https://repo.magento.com/",
            "exclude": ["channelengine/magento2"]
        }
     ],

   • Open the terminal and run:

     composer require channelengine/magento2

   • Enable the extension:

     bin/magento module:status ChannelEngine_Magento2

   • Clear static view files:

     bin/magento module:enable ChannelEngine_Magento2 --clear-static-content

   • Upgrade the setup:

     bin/magento setup:upgrade

   • Compile the application:

     bin/magento setup:di:compile

   • Verify the extension is enabled:

     bin/magento module:status 

   • Clean the cache:

     bin/magento cache:clean

2. After you install the extension, go to System, Integrations. The ChannelEngine integration should be listed.

   

3. Click Activate.
4. In the ChannelEngine dialog box, verify the different endpoints to which ChannelEngine needs access.
   • POST /rest/default/V1/guest-carts
   • POST /rest/default/V1/orders
   • GET /rest/default/V1/orders/{id}
   • POST /rest/default/V1/order/{orderId}/invoice
   • POST /rest/default/V1/order/{id}/channelengine
   • POST /rest/default/V1/guest-carts/{cartId}/items
   • POST /rest/default/V1/guest-carts/{cartId}/channelengine
   • POST /rest/default/V1/guest-carts/{cartId}/shipping-information
   • PUT /rest/default/V1/guest-carts/{cartId}/order
   • GET /rest/default/V1/categories
   • GET /rest/default/V1/products/attributes
   • GET /rest/default/V1/products
   • GET /rest/default/V1/taxRules/search
   • GET /rest/default/V1/taxRates/search
   • GET /rest/default/V1/configurable-products/{sku}/children
   • GET /rest/default/V1/stockItems/{productSku}
   • GET /rest/default/V1/inventory/get-product-salable-quantity/{sku}/{stockId}
   • GET /rest/default/V1/shipments
   • GET /rest/default/V1/orders
   • GET /rest/default/V1/store/storeConfigs
5. If you are not logged in to ChannelEngine, a pop-up redirects you to the ChannelEngine login page.
6. If you have multiple ChannelEngine environments, you can now select the ChannelEngine environment to integrate with Adobe Commerce.
7. If you have multiple store views, you can now select the store view that you want to integrate with.

Setup

Once you have connected Adobe Commerce with ChannelEngine, an Adobe Commerce 3.0 plugin is created on ChannelEngine. If this is not yet visible, contact your implementation specialist or customer success manager to verify the installation.

Connection

1. First, open the plugin. On the dashboard, click Plugins, Adobe Commerce.
2. Go to Setup, Connection. Choose an authentication method: OAuth or token-based.
   • Choose OAuth if you do not use special characters in your SKUs, e.g.: '/'. 
   • If you do use special characters in your SKUs and still prefer OAuth authentication, then take steps to optimize your web server settings to try to prevent stock update issues from ChannelEngine to Adobe. Check out the FAQs below.
   • Choose Token-based if you do not use 2FA and do use special characters in your SKUs.

3. The required settings should be automatically entered via the Adobe Commerce integration flow. Double-check if the correct Store URL and Store view code are filled in. If they are empty, ChannelEngine's plugin cannot connect to your Adobe Commerce store and import or export data.
   • Store URL - the URL where the main store for Adobe Commerce is located. E.g.: https://www.mystore.com/.
   • Store view code - the store view code of the store view you wish to connect with. E.g.: default.
4. The remaining settings depend on your selected authentication method.
   • OAuth-based authentication:
     • OAuth consumer key
     • OAuth consumer secret
     • Access token
     • Access token secret
   • Token-based authentication:
     • Adobe Commerce username
     • Adobe Commerce password

Plugin-specific settings

• Merchant product number alias in Adobe Commerce - the Merchant product number (MPN) is mapped to the Adobe Commerce Product ID by default, but it can be mapped to the SKU instead. This setting can only be configured once and cannot be changed later.
  • If selecting Product SKU, then on ChannelEngine, the SKU is mapped to the Merchant product number, and the product ID is mapped to the Vendor product number.
  • If selecting Product ID, then on ChannelEngine, the Adobe Product ID is mapped to the Merchant product number, and the SKU is mapped to the Vendor product number on ChannelEngine. If you select the MPN alias as the Product ID, the three-level product structure is no longer supported.

• Adobe Commerce version - the version of your Adobe Commerce software. E.g.: Magento/2.4 (Enterprise).
• Use order line description provided by the channel - enable this setting to include the product description in the order export to Adobe Commerce.
• Export region - enable the setting to include the region name from the billing and shipping addresses in the order export to Adobe Commerce.
• Order comment - use this field to define the order comment format, using text and placeholder tags. For guidance on defining the order comment format, check out the Orders section below. 

Advanced settings

• URL suffix - the URL suffix for product pages on Adobe Commerce. If you use the default URL rewrite in Adobe Commerce, this field can remain empty. If pages show .html at the end, it needs to be included.
• Submit order prices excluding VAT - if you have enabled VAT calculation on Adobe Commerce (i.e.: so your store orders are placed without the default VAT), make sure to enable this setting to prevent double VAT calculation on marketplace orders. When enabled, order amounts are consistently synchronized with Adobe Commerce, exclusive of VAT. 

• Submit shipping prices excluding VAT - if you have enabled VAT calculation on Adobe Commerce, make sure to enable this setting to prevent double VAT calculation on marketplace orders. When enabled, all shipping amounts are consistently synchronized with Adobe Commerce, exclusive of VAT. If disabled, the shipping amounts are synchronized with Adobe Commerce, inclusive of VAT.

  NB: when both VAT-related settings are disabled, ChannelEngine exports order and shipping amounts to Adobe Commerce, including VAT. However, tax amounts and percentages are not displayed in the Adobe Commerce back end, as Adobe treats externally calculated values as pre-tax.
  
  To display tax amounts and percentages explicitly in Adobe Commerce, enable both VAT-related settings and use Adobe Commerce's tax calculation instead. To learn more, check out the Tax configuration settings.
• Enable synchronization of orders fulfilled by marketplace - enable this to include orders fulfilled by marketplaces in the order export to your webstore.
• Canceled order line handling - determines how ChannelEngine handles canceled order lines, e.g.: from a cancelation request. The options are: include these order lines in the export to Adobe Commerce; exclude these order lines in the export to Adobe Commerce; or automatically cancel unknown orders – and not export them to Magento. The default value is to include these order lines.
• Generate three-level product structure - enable this setting to generate the three-level product structure (i.e.: grandparent, parent, and child) on ChannelEngine. Note that only products of type 'configurable' can be converted into a three-level product structure. Products of type 'simple' are created as standalone products. 
• Product option for parent - (only enabled if Generate three-level product structure is enabled) use this setting to specify the option that distinguishes parent products from one another. For guidance on specifying the parent option, check out the Product variations section below. 
• Enable stock import - when enabled, the stock import is handled by the specific "import product stocks from merchant task" on ChannelEngine, and the Update stock on product import setting is set to No. 
• Update stock on product import - enable this to update the product's stock whenever the product import to ChannelEngine is performed.
• Update prices on product import - when enabled, ChannelEngine imports updates on the price, list price, and purchase price into the product data, and the special price is imported as product extra data. By default, this setting is turned on.
• Enable bulk stock import - (appears only if Enable stock import is enabled) enable this setting to either retrieve the physical quantity or salable quantity of stock from every sales channel on which the product is listed.
• Stock import type - (appears only if Enable stock import is enabled) to retrieve the physical quantity, select Physical stock. To retrieve the salable quantity, select Salable stock. 
• Inventory management stock ID - (appears if Stock import type setting to Salable stock or if Enable bulk stock import is enabled) if you are using Adobe Commerce's own inventory management system and have multiple stock locations set up, use this setting to enter the correct warehouse ID as an integer. The default value is 1. Note that in Adobe Commerce, you can find the stock ID on the Manage stock page by going to Stores, stock. Make sure to also set the Stock import type setting to Salable stock so that the stock is imported from that specific stock location.
• Enable synchronization of orders fulfilled by merchant - enable this to synchronize orders that come in from marketplaces via ChannelEngine and must be fulfilled by you, the merchant.
• Check for return tracking code - enable it to capture a return tracking code for marketplaces that require it. When creating a shipment for marketplaces such as Zalando, OTTO Market, or About You, enter the return tracking code in this tracking number field. If the return tracking code is not provided, ChannelEngine rejects the shipment. To learn more, check out the article Adobe Commerce 3.0: return tracking code.
• Return T&T number custom title - (only appears if Check for return tracking code is enabled) define a unique title for the return T&T code that must be 3-64 characters long and only contain alphanumeric, hyphen, and underscore characters.
• Enable synchronization of merchant returns - enable this to synchronize merchant returns. Returns that are registered in your webstore are imported into ChannelEngine and exported to the marketplace.
• Enable synchronization of marketplace returns - enable this to synchronize marketplace returns. ChannelEngine starts exporting any returns registered on the marketplace to your Adobe Commerce webstore.

Activation

1. On the Activation tab, switch the Activate synchronization for Adobe Commerce toggle to activate the Adobe Commerce 3.0 plugin.

2. Once the plugin is activated, data import and export tasks are scheduled and executed automatically. You can see the latest performed and scheduled tasks under the Dashboard tab of the plugin's settings.

   

3. If you run into issues during any of these steps, contact ChannelEngine's Support team or check out the Adobe Commerce 3.0: common integration issues and error messages article.
4. ChannelEngine adheres to Adobe standards and guidelines and is officially validated by Adobe through the Adobe Commerce App Assurance Program. The Adobe Commerce plugin is designed for standardized Adobe Commerce (née Magento) setups. Additionally, while ChannelEngine has seen successful integrations of the ChannelEngine Adobe Commerce plugin with various third-party plugins, ChannelEngine cannot guarantee compatibility with every setup combination.
5. Any incompatibility with third-party plugins or highly customized Adobe Commerce settings is the responsibility of the user or the third-party plugin provider to resolve.

Overview

Product variations

On Adobe Commerce, the top option corresponds to 1 on ChannelEngine.

The screenshot below shows an example of the variation setup on Adobe Commerce. Color is the top attribute (option 1), and Size is the next attribute (option 2).

Stock

It is a known issue that Adobe Commerce versions 2.4.6 and up cannot reliably import stock levels for SKUs that contain a slash (/) if you use OAuth. In the API request URL, the SKU gets URL-encoded (e.g.: / becomes %2F), but this encoding causes a mismatch in the OAuth 1.0 signature generation/validation process. 

To troubleshoot this situation, you can try to modify your web server settings. To try to work around this issue, you can try to configure AllowEncodedSlashes NoDecode for nginx. Another workaround that another Adobe user tried is:

index 898f70e2..af2fdc85 100644
--- a/vendor/magento/framework/Oauth/Oauth.php
+++ b/vendor/magento/framework/Oauth/Oauth.php
@@ -203,7 +203,19 @@ class Oauth implements OauthInterface
             $requestUrl
         );
 
-        if (!Security::compareStrings($calculatedSign, $params['oauth_signature'])) {
+        $calculatedSignWithEncodedPercentage = $this->_httpUtility->sign(
+            $allowedSignParams,
+            $params['oauth_signature_method'],
+            $consumerSecret,
+            $tokenSecret,
+            $httpMethod,
+            str_replace('%', '%25', $requestUrl)
+        );
+
+        if (
+            !Security::compareStrings($calculatedSign, $params['oauth_signature']) &&
+            !Security::compareStrings($calculatedSignWithEncodedPercentage, $params['oauth_signature'])
+        ) {
             throw new AuthException(new Phrase('The signature is invalid. Verify and try again.'));
         }
     }    

Neither of the above suggestions is guaranteed to solve the stock import problem. Refer to the unresolved ticket on GitHub
Rest API calls give 401 Unauthorized in response since Magento 2.4.6 #37278, and reach out to Adobe to release a permanent fix to this issue.

Orders

Order comments appear in the Order total, Notes for this order section on Adobe Commerce as text, using the format that you specify here. 

By default, the following text placeholder tags are available to use: 

• ChannelName - the name of the channel where the order was placed.
• ChannelOrderNo - the unique order number that is recognized by the channel.
• CommercialOrderNo - the unique order number that the end buyer sees on the channel.
• ChannelProductNo - the unique product number that is recognized by the channel.
• ChannelCustomerNo - the unique customer number that is recognized by the channel.

The default order comment text is Channel: [ChannelName], ChannelOrderNo: [ChannelOrderNo], CommercialOrderNo: [CommercialOrderNo], ChannelProductNo: [ChannelProductNo], ChannelCustomerNo: [ChannelCustomerNo].

Rephrase the text as desired, and place any or all of the above placeholders into the text. If a placeholder tag is unrecognizable or empty, then ‘NULL’ is printed in the order comment. E.g.: when ChannelCustomerNo is empty in an order placed on the channel Boulanger, then Channel: [ChannelName], Channel Customer No: [ChannelCustomerNo] results in Channel: Boulanger, Channel Customer No: NULL.

FAQs

How often does each task run on Adobe Commerce 3.0?
By default, the Adobe Commerce 3.0 plugin follows the schedule below.

What do I encounter the 'Invalid signature' error?
You may encounter the 'Invalid signature' error if you upgraded your Adobe Commerce to version 2.4.3 or higher but did not reauthorize your plugin in Adobe Commerce back-end. 

1. In the Admin sidebar, go to System, Extensions, Integrations.
2. Find the ChannelEngine's integration with the Active status.
3. In Activate column, click Reauthorize.
4. Approve access to the API resources and save the integration tokens.

Can I retrieve marketplace order extra data via Adobe Commerce 3.0?
It is currently not possible to retrieve order or order line extra data via ChannelEngine’s Adobe Commerce plugin. This is due to the complexity and variety of marketplace order extra data fields, which make them difficult to standardize.

If you must retrieve specific order extra data fields, you will need to build a custom integration with ChannelEngine to fetch this data.

Why does ChannelEngine parse buyer addresses, and how can I disable this?
ChannelEngine parses buyer addresses to standardize their format and improve compatibility with carrier and fulfillment systems. However, parsing does change the original structure, especially for US addresses, where the house number appears first – unlike in Europe.

To retrieve the original shipping and billing addresses from the marketplace, use the Disable address parser setting. To do this, go to Settings, Settings, Address and toggle Disable address validation. To learn more, check out the article ChannelEngine: address parsing.

Why does Adobe Commerce change a zero price back to the product's original price?
If you set a product’s price to zero – e.g.: to offer a 100% discount to a marketplace customer like a TikTok influencer – Adobe Commerce automatically replaces the zero price with the product’s original price when the order is imported. This is a default behavior on Adobe Commerce to prevent orders with a zero value.

Why do I get the error "Sorry your guest checkout is not available in Magento"?
This error occurs because Adobe Commerce requires the Allow guest checkout setting to be enabled. If this setting is disabled, ChannelEngine’s plugin cannot synchronize orders.

By default, the plugin creates a guest cart on Adobe Commerce and converts it into an order, which then can be processed (e.g.: canceled or shipped). If guest checkout is not allowed, this process fails and triggers the error.

To resolve this error, in your Adobe Commerce back-end, go to Stores, Settings, Configuration, Sales,  Sales, Checkout, Checkout options, and set Allow guest checkout to 'Yes'.