All you need to know before starting...


This page aims at sharing some best practices regarding our Akeneo connector for Adobe Commerce implementation and some basic guidelines to keep in mind.

What you need to know

First of all, Akeneo Connector is a bridge between Akeneo PIM (in its core version) and Adobe Commerce (in its core version). Why is it important to notice? Because our Akeneo Connector is an agnostic connector that is independent of customer's specificities. Our goal is to provide a solid technical basis to plug Akeneo PIM into a Adobe Commerce (M2) instance. If some particularities are required, this is not a problem; ask your IT referral (integrator or IT team) to customize the connector.

Another important notion here is to consider that Akeneo Connectors are 3rd-party plug-ins and therefore, we are fully impacted by the Adobe Commerce system limitations. The very first rule you need to keep in mind is "Think agnostic" (if you have to choose between many data model in the PIM, prefer a native Adobe Commerce approach). This means that, if in Adobe Commerce a piece of data is managed as an integer, please highly prefer creating an integer field in your Akeneo PIM rather than considering the connector will take care of it (the connector will do the job, but the performance will decrease).

Talking about performance

We are often asked about the metrics and performance of Akeneo Connectors. Unfortunately, this is not that easy. In general, please note that three main criteria impact the performance of the connector:

  • The catalog volume: even if that's the first one that comes to mind it is not the only one to consider.
  • The catalog complexity: indeed, importing 500 000 products can be an easy task if the product is described by "just" a name, a description, and an image. However, if the product is very complex (high number of attributes, many reference entities, plenty of variations, etc.), importing 2 000 products can be a very painful and long process.
  • The Adobe Commerce limitations: in addition to what we already said in the introduction, Adobe Commerce has its own limitations.

So what can I do to preserve my connector's performances?

  1. Always prefer direct data mapping between Akeneo PIM and Adobe Commerce, this way you don't need to rely on Adobe Commerce to convert the PIM data into the required format. By doing so, you will help your system to be more efficient.
  2. One of the most impactful use is the Asset Binaries use. So if it is possible for you to consider using a DAM and the Asset Manager (media link & file link) instead of Image binaries directly uploaded in the PIM, you will save a lot of time. Prefer saving a string of characters (URL) versus an actual HD picture.
  3. Challenge the amount of data you will copy over to Adobe Commerce. You might have attributes on Akeneo PIM that are not needed for your storefront. Filtering them out of synchronization can help you save some time during imports.

Full import or partial import?

There are two ways to import product data:

Full import: this is the longest import process because everything, including media, will be synchronized between Akeneo PIM and Adobe Commerce. However, this full import happens once for the very first synchronization used to build your catalog on Adobe Commerce side. Then, most of the time, it is automatically executed every night to resync everything. The three performance criteria, listed above, highly impact this import process, and this is why this process is often an automated task.

Differential import: The system can sync only new products when it's necessary. However, to reconstruct some data on the Adobe Commerce side, some tasks have to be run as a full import anyway (e.g., categories are fully imported even in a differential import). However, this differential import process will allow you to decrease the needed import time. This type of import is used daily to resync data that has changed in the days. This one is often a manual operation.

You will have to define your data update policy to adjust the threshold between full import and differential import.

What are the best practices to customize Akeneo Connector?

As part of our Adobe Commerce online training, here are the tech guidelines to help you create a customization on top of the Akeneo Core version of the connector.

Use composer to deploy

Do not edit the initial code and prefer the override procedure. If you installed the connector via composer as recommended in the online documentation, you will not be able to edit the code (because the core code is designed as a dependency)


Override the connector

Adobe Commerce comes with a new dependency injection system. Which dependencies to inject are controlled by the di.xml file. Each module can have a global, and a local scope di.xml file:


Please note that it is possible to override, and you have multiple ways to do so:


Let’s take an override example. We want to override the catalog product class (which is defined in the di.xml file of the Catalog module):

 <preference for="Magento\Catalog\Api\Data\ProductInterface" type="Magento\Catalog\Model\Product" />

To override this class, all we need to do is to create a file that will extend the original class:

 <preference for="Magento\Catalog\Api\Data\ProductInterface" type="Akeneo\Catalog\Model\Product" />
namespace Akeneo\Catalog\Model;
 class Product extends \Magento\Catalog\Model\Product
 // code

The order of module dependencies is very important, and to make sure that this order is the right one, the sequence has to be defined in etc/module.xml.



By extending a class with multiple classes, you can cause conflict. To avoid that, Adobe Commerce has defined the notion of plugin. Plugins are a great solution to extend a class and not change it. Just like for the class declaration, the plugins are declared in the di.xml file. The plugin system intercepts a method call before, after, or around its call. Let’s take an example. First, the di.xml file

 <type name="Magento\Catalog\Api\Data\ProductInterface">
 <plugin name="Akeneo_catalog_product" type="Akeneo\Catalog\Plugin\Model\Product" />

And, then, as described earlier, the three catching methods: Before, After, Around


Before executes your plugin prior a given method. The only constraint is that your plugin needs to return the same number of arguments than the method accepts (in an Array)

namespace Akeneo\Catalog\Plugin\Model;
 class Product
 public function beforeSetPrice(\Magento\Catalog\Model\Product $subject, $price)
 $price += 10;
 return [$price];


This is the way to execute a procedure after a method is executed. The After method will work with the same number of arguments that the initial method plus one additional argument (the return argument of the initial method). The extended method needs to have the same name with the prefix “after”

namespace Akeneo\Catalog\Plugin\Model;
 class Product
 public function afterGetName(\Magento\Catalog\Model\Product $subject, $result)
 $result .= ' (Akeneo)';
 return $result;


Around is about using both the before and after methods in one shot. The extended method shall have the “around” prefix in its name.

namespace Akeneo\Catalog\Plugin\Model;
 class Product
 public function aroundSave(\Magento\Catalog\Model\Product $subject, \callable $proceed)
 // before save
 $result = $proceed();
 // after save
 return $result;

The plugin solution looks very interesting. However, it has some limitations, in particular it does not work with all types of methods. If you have those type of method, please consider another overriding solution:

  • Objects that are instantiated before Magento\Framework\Interception is
  • bootstrapped
  • Final methods
  • Final classes
  • Any class that contains at least one final public method
  • Non-public methods
  • Class methods (such as static methods)
  • __construct
  • Virtual types

How to ensure the success of my integration?

This is pretty easy: you should test the Connector as early as possible in the integration process. By doing so, you will challenge the data model and ensure the efficiency of the mapping.

Please note that evaluating the core connector version to know if it fits your needs belongs to your technical team or your integrator. This is why the earlier you start testing, the earlier you are confident in the connector compatibility and its adoption.


You should ask yourself:

  1. Are Akeneo PIM and/or the eCommerce platform customized in any way? If they are, that should raise a warning.
  2. Are all the project actors aware of their responsibilities?, if there are any doubts, make sure everyone attends the Akeneo Akademy Training.
  3. Does the system integrator (or the IT team in charge of the integration) know that:
    • every month, there will be a new version of Akeneo Connector and they will have to update their Connector accordingly (with or without customizations)?
    • if there is a customization, the related support (level 1 to 3) and maintenance fall with the team that has developed this customization.
  4. The bigger the catalog, the sooner the Connector has to be tested, especially in terms of performance and synchro data policy definition.
  5. The more complex the catalog, the sooner the connector mapping has to be considered. Waiting until the end of the project would take a lot more time which might lead to delaying the go-live date and create frustration.
  6. Be brave, don't worry about trying out new things. Benefit from this opportunity to challenge your existing data model and to get rid of all the complexity inherited from a legacy solution. Our advice here is that this is better to modify an existing data model slightly on the eCommerce side to be able to efficiently map and smoothly import your data rather than recreating a legacy complexity in the PIM.
  7. An Akeneo Connector will do what it is created for: to plug any standard PIM into a standard version of Adobe Commerce, by maintaining the highest performance and scalability for all its users. If Akeneo Connectors tests are not up to your performance standards, then there are two options for you:
    • Not using the Akeneo Connector at all and creating yours from scratch (and we are totally fine with that)
    • Creating customizations to enhance performances according to your performance standard.