Install Akeneo Connector for Magento 2 on an existing Magento 2

#Before installing the connector

You might be setting up an Akeneo PIM instance for the first time and you want to connect it to your existing Magento 2.

Installing and configuring Akeneo Connector for Magento 2 is only a step of your migration process.

Indeed, in order to ensure that the data transfer and the connection between the two systems goes as smoothly as possible, there are a few steps you need take in account before configuring your connector.

#Akeneo PIM catalog structure

You need to think about an Akeneo PIM catalog modelization that will correspond to your Magento 2 existing catalog structure. If the data structure you choose inside Akeneo PIM contrasts from your current setup in Magento 2, you might be facing issues during data transfers and incompatibilities due to the many differences between your two systems.

On the other hand, setting up an Akeneo PIM instance for your business can also be the right time to review some of your catalog structure or your enrichment workflow.

You have to be aware that those structural changes might impact your existing Magento 2 catalog structure, and also the synchronizations with the connector.

In this case, some cleaning or restructuring inside Magento 2 might be needed before setting up the connector.

#Initializing your catalog data from your Magento 2 or your ERP in your Akeneo PIM instance

After setting up your new Akeneo PIM instance, you will need to import your current catalog data, either from your existing Magento 2 or your ERP.

This process is specific, and will depend on your choices in terms of Akeneo PIM catalog structure and internal organization.

Akeneo Connector for Magento 2 is focused on synchronizing data from Akeneo to Magento 2 but it will never transfer data from Magento 2 to Akeneo PIM. This transfer has to be done independently.

#Synchronizing your Akeneo PIM data to your Magento 2 for the first time

Once your Akeneo PIM instance is ready, the connector installed and configured on your Magento 2, you can now proceed to your first synchronization between both systems.

Keep in mind that this kind of connection requires a lot of testing and data analysis afterward to make sure that there are no misconfigurations or undesired side effects.

A production environment should not be used to test the first synchronization between Akeneo PIM and Magento 2.

We recommend you follow the guide below to check the integrity of your different Magento 2 entities, reconfigure it if necessary after the first import and also check the good behavior of your Magento 2 online store.

#Installing Akeneo Connector for Magento 2 on an existing Magento 2

As the catalog and entity structures between Akeneo PIM and Magento 2 are different, Akeneo Connector for Magento 2 uses a custom table (akeneo_connector_entities) to store the relations between Akeneo PIM entities and Magento 2 entities. Those relations are created once an entity has been imported with the connector.

Installing the Akeneo Connector for Magento 2 on an existing Magento 2 with existing entities like products or attributes that have not been imported with the connector means that the relations in Akeneo Connector custom table are not present yet, and that the Akeneo Connector doesn't know which Akeneo PIM entity is related to which Magento 2 entity.

Since the 100.3.4 version of the Akeneo Connector for Magento 2, it is possible to automatically map some entity types from Akeneo PIM to existing entities in Magento 2 during the first import.

The supported types are Attributes, Options and Products. Below are the explanations for each entity and global recommendations to successfully connect your Akeneo PIM and your existing Magento 2 with the Akeneo Connector for Magento 2.

Always make sure to backup your data and to test the synchronization on an existing Magento 2 in a non-production environment beforehand


At this point, it is not possible to automatically link Akeneo PIM categories and existing Magento 2 categories that have not been created with the connector.

This limitation comes from the fact that there is no category code inside Magento 2 that can be linked to the category code inside Akeneo PIM.

Our recommendation in this case is to import your category tree from Akeneo PIM with Akeneo Connector for Magento 2, and use it to replace your existing Magento 2 tree, in your Magento 2 "Root category" store configuration when you are ready to move to the new structure.

When doing so, make sure that your products have been associated with your new category tree.


At this point, it is not possible to link existing families from Magento 2 to Akeneo PIM families as there is no code inside Magento 2 to match with the Akeneo PIM family code.

Our recommendation is to import new families from Akeneo PIM, let the product job link your products to the new families, and delete the old families.

A family (attribute set) inside Magento 2 can be deleted only if no products are associated to it.


When importing for the first time to an existing Magento 2 instance, attributes with the same code inside Akeneo PIM and Magento 2 will be automatically linked in the Akeneo Connector entity tables.

Make sure that the attribute type in Magento 2 matches your attribute type in Akeneo PIM.

If not, a warning message will appear and the attribute will be skipped.

Consult the Akeneo Connector default attribute type mapping for more information: Attribute types

#Attribute options

When importing for the first time to an existing Magento 2 instance, attribute options are automatically linked to your existing Magento 2 attribute options based on their "Admin label".

If an option in Magento 2 for a specific attribute has an "Admin Label" matching the Akeneo PIM option label in your Magento 2 admin locale, the connector will setup the link during the first import.

Since the 101.6.0 version of the Akeneo Connector for Magento 2, you can set Akeneo attribute option code as Admin label in Magento 2. If you do so, the mapping will be based on the code of your attribute options in Akeneo corresponding to your existing Magento 2 attribute option Admin label. For more information, please consult the associated documentation: Configure Attribute Options

#Product models and family variants

Product model and family variant jobs has been removed since the 101.0.0 version of the Akeneo Connector for Magento 2 and merged into the Product job

Product models and family variants data is stored into internal Akeneo Connector tables and will be used during the Product import job process.

This data doesn't need any link to Magento 2 entities so you will just have to launch the corresponding jobs to fetch the data from Akeneo PIM before launching the product job.


Products are automatically linked from your existing Magento 2 product SKU and the Akeneo PIM product identifier. It includes simple and configurable products in Magento 2 (product models and variant products in Akeneo PIM).

The data coming from Akeneo PIM will replace the existing data inside your Magento 2 products.

Be curious! Take a look at these related articles