Mapping Products

Summary

Introduction

The role of the Akeneo Connector for Adobe Commerce is to push your product data from your PIM to Adobe Commerce, but be careful, not all product types are handled in the same way. Check the table below to know how to configure each product type :

Adobe Commerce product type Related documentation article
Simple Products Check the Product type mapping section in this article to configure your simple products.
Virtual Products Adobe Commerce virtual products are considered as simple products in Akeneo PIM. Check the “product type”  section in this article for mapping configuration.
Configurable products Configurable are Product Model within Akeneo PIM. Check the following article to configure your configurable products: Map Product models
Grouped products Grouped product consists of simple standalone products that are presented as a group. Check the "Grouped product" section in this article for mapping configuration.
Downloadable products Those products are not handled by the PIM nor the connector. You can customize the connector.
Bundle products Bundle products are covered since 104.3.0. 
Gift cards Those products are not handled by the PIM nor the connector. You can customize the connector.

Mapping available for product types and status 

Product Type Mapping for Virtual and Simple Products

Available since the 102.1.0 version of the Akeneo Connector for Adobe Commerce.      

The “product type” mapping is used in the connector to map Simple products and Virtual products to Adobe Commerce product types.

To do so, you must use a single select attribute in Akeneo and configure your attribute option codes matching Adobe Commerce product types as follows:

  • Simple product: simple
  • Virtual product: virtual

If a code is not matching an Adobe Commerce product or is empty, the product will be created as a simple product.

 

The mapping is done in the connector configuration page, in Products:

Connector parameter Adobe Commerce information
Akeneo Attribute Code for Product Type Mapping PIM "Product type" attribute code (ex: product_type)

For now, this attribute can only be used to create virtual products or simple products.

To create Configurable (configurable) or Grouped (grouped) type, please refer to the below articles.

 

Akeneo attribute code for SKU

In the connector, you need to tell Adobe Commerce the product reference attribute code used in Akeneo. This attribute, a text area within the PIM, will be used for the eCommerce product SKU.

Connector parameter

Adobe Commerce information

Akeneo attribute code for SKU

Mapping used in Serenity, Growth and V7.0 Akeneo edition. The SKU behavior now looks closer to a normal attribute. If empty, run a fault and stop the product flow.

Since the version 103.4.0 of the Akeneo Connector, the product SKU attribute code is free. Previously it had to be called "SKU".

With Akeno Serenity, Growth and 7, the product is now identified by an unique identifier called UUID, generated in Akeneo. This UUID is the unique link between the product in the PIM and Adobe Commerce.

 

Product Status Mode

Available since the 102.2.0 version of the Akeneo Connector for Adobe Commerce. 

You can choose between multiple product status modes in the connector configuration page, in the Products section:

Connector parameter Adobe Commerce information
Product Status Mode Default status, Status based on completeness level or Attribute Mapping

Check the tabs to see how each mode works :

Default status

Since the 100.4.2 version of the Akeneo Connector for Adobe Commerce (CE & EE), you can choose to enable or disable new products by default in the connector configuration page, in the Products section.

Connector parameter Connector Default options
Default product status Choose Enable or Disable

If a product is "enabled" in Akeneo PIM, it will be created with the default status defined in the configuration.

During updates, his current status won't be modified.

 

If a product is "disabled" in Akeneo PIM, it will be disabled in Adobe Commerce, regardless of the configuration.

 

Akeneo PIM "enabled" status is a system attribute value that should not define the activation of a product in Adobe Commerce.

 
 
 

Status based on completeness level

Since the 102.2.0 version of the Akeneo Connector for Adobe Commerce, you can choose the "Status based on completeness level" product status mode in the connector configuration page, in the Products section:

Connector parameter Adobe Commerce information
Enable Simple Products per website if completeness in channel is equal or greater than Completeness percent (from 0 to 100)

When using the "Status based on completeness level" product status mode, you can enable simple products if their completeness level is equal or greater than the number configured.

The completeness will be fetched at each import, and the simple product status will vary on each updates depending on their current completeness level.

Examples:

  • Setting the completeness level to 100 will only enable simple products that are 100% complete
  • Setting the completeness level to 50 will only enable simple products that have a completenes value of 50% or superior

The product status will be applied per website in Adobe Commerce, so depending on the completeness level of your products, they might be enabled for a website but not for the others

The product completeness for a Channel <> Website mapping will be calculated from every Store View locales available in your Adobe Commerce website

 

As product models don't have completeness, they can't be enabled or disabled from a completeness level

Connector parameter Adobe Commerce information
Default Configurable Products Status Enabled or Disabled

The behavior of the "Default Configurable Products Status" is the same as the "Default status" mode

 
 

Attribute mapping

Starting from version 102.5.0 of the Akeneo Connector for Adobe Commerce, you have the option to select the "Attribute mapping" product status mode within the connector's configuration page, specifically in the "Products" section. This feature offers enhanced control over product statuses during the integration.

Connector parameter Akeneo PIM parameter
Akeneo Attribute code for Simple product statuses Akeneo Yes/No attribute code
Connector parameter Akeneo PIM parameter
Akeneo Attribute code for Configurable product statuses Akeneo Yes/No attribute code

It's important to note that the Akeneo attribute used for this mapping must be a global or scopable Yes/No Attribute, as localizable values are not used. Product statuses cannot be adjusted at the Store View level; they remain consistent across all Store Views.

This feature allows you to enable or disable products at the website level in Adobe Commerce. You can change the visibility status at the store view level but not the product status.

 

With the "Attribute mapping" mode, you can map a Yes/No attribute from Akeneo to the "status" attribute in Adobe Commerce, enabling you to manage product statuses effectively. 

This mode permits you to designate two different attributes, one for simple products and one for configurable products (product models in Akeneo).

Under this mode, product statuses will change after each update based on the Yes/No attribute's value in Akeneo: "Yes" will enable the product, while "No" will disable it.

In the event that the attribute code specified does not exist in Akeneo, is not a valid Yes/No attribute, is not found on a product, or is localizable, the connector will take the necessary steps to disable the corresponding products in Adobe Commerce, ensuring data integrity and consistency.

 
 

Visibility mapping

Adobe Commerce incorporates a native "visibility" attribute that determines where a product is displayed on the website. 

Since 103.4.0

With the Akeneo Connector for Adobe Commerce, starting from version 103.4.0, you can effectively map an Akeneo select attribute with Adobe Commerce product visibility. This mapping takes place in the connector's configuration page under the Products section.

Connector parameter title Connector default option
Enable Visibility Mapping From Akeneo Attribute Yes or No

When you set Enable Visibility Mapping From Akeneo Attribute to No, the default visibility settings are applied as follows:

  • Simple products : visible in “Catalog, Search”
  • Product models : visible in “Catalog, Search”
  • Product variants : “Not Visible Individually”

However, when you set it to Yes, the attribute mapping becomes active. You can configure this mapping with the following fields:

Connector parameter title Connector default option
Default product visibility Select between: Not visible individually, Catalog, Search, Catalog & Search

This parameter allows you to set a default visibility for products in case no value is found in Akeneo for the visibility mapping.

Connector parameter title Akeneo PIM parameter
Akeneo Attribute Code For Simple Product Visibility Akeneo Attribute Code for the select attribute mapped to simple products visibility

Within this feature, it's important to note that product variants are treated as simple products. Consequently, their visibility is controlled by the same attribute used for simple products.

 
Connector parameter title Akeneo PIM parameter
Akeneo Attribute Code For Configurable Product Visibility Akeneo Attribute Code for the select attribute mapped to configurable products visibility

To ensure proper functionality, it's crucial to map an Akeneo simple select attribute to Adobe Commerce visibility. This select attribute can be non-scopable, non-localizable, localizable, scopable, or have a combination of these properties. Additionally, the select attribute must include the following options to work effectively:

Connector parameter Adobe Commerce information
1 Not visible individually
2 Catalog
3 Search
4 Catalog Search
 
 

Before 103.4.0

In versions prior to 103 of the connector, mapping was not possible, and visibility was managed according to default settings:

  • Simple products : visible in “Catalog, Search”
  • Product models : visible in “Catalog, Search”
  • Product variants : “Not Visible Individually”
 
 

Product associations

Available since the 101.2.0 version of the Akeneo Connector for Adobe Commerce. 

You can configure the code of the associations to map with Related, Upsell and Cross-sell products in Products:

Related products

Connector parameter title Akeneo PIM parameter
Akeneo association code for Related products Fill in the association code from Akeneo

The default value for this configuration is: SUBSTITUTION

 
 
 

Upsell products

Connector parameter Akeneo PIM parameter
Akeneo association code for Upsell products Fill in the association code from Akeneo

The default value for this configuration is: UPSELL

 
 
 

Cross-sell products

Connector parameter Akeneo PIM parameter
Akeneo association code for Cross-sell products Fill in the association code from Akeneo

The default value for this configuration is: X_SELL

 
 
 

This configuration cannot handle quantity associations, please only use 2-way associations or default associations.

To know how to manage association with quantity, please read the section Grouped product.

 

Grouped product

Grouped Products are a default type of products in Adobe Commerce but are not managed in Akeneo. To handle them through the connector, a specific modelization is required in the PIM.

Grouped products allow customers to purchase a set of related products as a single unit. Each product within the group retains its individual identity and can be selected or deselected by the customer. For example, a grouped product might include a camera, a camera bag, and a memory card. Customers can choose to buy one, two, or all three items.
It is different from bundle products. Bundle products, on the other hand, enable merchants to create customizable product bundles. Customers can choose from a list of component products to build their own bundle.

 

Modelization

Modelization within the Akeneo PIM: Setup grouped products in the PIM

Step 1 - Create a specific family for Grouped products

  1. First, go to "Setting > Families"  
  2. Create a new family dedicated to your "Grouped" products.
  3. Make sure to associate or create the necessary attributes within this family.

Note that Adobe Commerce Grouped product prices are calculated from the price of their associated products.

 

Step 2 - Create a quantified association

  1. Go to "Setting > Association type"  
  2. Create a new Akeneo Association with quantity.
  3. This association will be the one that will contain the link between your Grouped products and their children.

You cannot manage Grouped product links with a two-way association or the default association type.

 

Step 3 - Create your "Grouped" products

  1. Since Akeneo doesn't have a specific "Grouped" product type, you'll need to create "Simple" products that represent your "Grouped" products
  2. Associate these "Grouped" products with the family you created for Grouped products in Akeneo

"Grouped" products in Akeneo must be represented as "Simple" products and  cannot be represented by “Product models”.

 

Step 4 - Associate your child products to your "Grouped" products

  1. In the "Associations" section of your "Grouped" products in Akeneo, link the child products that make up your "Grouped" product using the quantified association you created.

You can only link "Simple" or "Variant" products to your "Grouped" products.

 
 
 

Mapping

Mapping

Available since the 101.2.0 version of the Akeneo Connector for Adobe Commerce and for Akeneo Edition 5.X, Growth Edition and Serenity Edition. 

In the connector configuration page in Grouped products, you can configure grouped product families and quantity association mapping:

Connector parameter title Grouped product family code Quantity association code
Grouped product families and quantity association mapping Select Akeneo family code(s) Fill in Akeneo quantified association code(s)

Please make sure to only map quantified association in this configuration.

 
 

Import

Import

To import your Grouped products into Adobe Commerce, you need to run all the import jobs using the Akeneo Connector for Adobe Commerce. Your Grouped products will be imported as part of the Product job within the connector. This job will ensure that your Grouped products and their associated child products are transferred to Adobe Commerce successfully.

The Grouped product family is imported last to ensure that the linked products are created in Adobe Commerce. This sequencing ensures that the associated child products are properly set up before the Grouped products are imported, maintaining the integrity of your catalog structure.

 

Product models associated with a configured "Grouped" family in Adobe Commerce will not be imported through the connector. It's important to note this limitation when managing your product catalog, as these models will not be included in the import process.

 
 
 

Default tax class for a Website

In Adobe Commerce, the default tax class serves as the foundational setting for how taxes are applied to products. When a product doesn't have a specific tax class assigned, it automatically inherits the default tax class.

Within the connector configuration page, under the Products section, you have the option to select the default tax class for a particular Adobe Commerce website. This setting allows you to define the default tax class that should be applied to products associated with the specified website during the import process.

Connector parameter Adobe Commerce information
Default Tax Class None
  Taxable Goods
  Refund Adjustments
  Gift Options
  Order Gift Wrapping
  Item Gift Wrapping
  Printed Gift Card
  Reward Points

Custom tax classes created in Adobe Commerce will automatically appear in this field so you can assign them to your products.

Product swatches

Product swatches in Adobe Commerce are visual representations of product attributes like colors, sizes, or patterns. They provide a user-friendly way for customers to choose product options. Swatches can be either text-based, displaying attributes like "Red" or "Large," or visual, showing images of the options. These swatches enhance the shopping experience by making it easier for customers to select product variations.

Attribute mapping

Available since the 103.4.0 version of the Akeneo Connector for Adobe Commerce.

In the connector configuration, under the Attributes section, you can map an Akeneo attribute with “Text Swatch” or “Visual Swatch” attribute type in Adobe Commerce. To use this feature, the Akeneo attribute should be of the "Simple select" type. 

Connector parameter title Adobe Commerce information Akeneo PIM information Ref. Entity attribute code Visual Swatch option type
Swatch types mapping Select Swatch type (Text Swatch or Visual Swatch) Fill in the Akeneo single select attribute code Leave empty none

The design interface of the swatch display has some constraints, as both attributes and reference entities are presented within the same table. It is worth noting that the last two columns of the table are reserved exclusively for reference entity mapping.

 
 
 

Reference entity mapping

Available since the 103.5.0 version of the Akeneo Connector for Adobe Commerce.

In the connector configuration, under the Attributes section, you can map an Akeneo reference entity single link with “Text Swatch” or “Visual Swatch” attribute type in Adobe Commerce. 

You can import the color (hexadecimal) and the image from Akeneo through reference 

Connector parameter Adobe Commerce information Akeneo PIM information Ref. Entity attribute code Visual Swatch option type
Swatch types mapping Select the Swatch type (Text Swatch or Visual Swatch) Fill in the Akeneo reference entity single link attribute code The code of the reference entity attribute used for the image/color Select  color or image type for swatch (Hexadecimal or image)

The Community Edition of the Akeneo Connector doesn't manage Reference entities (As this feature is only available on PIM Enterprise Edition).

 
 
 

Bundle product 

Since 104.3.0, you can manage bundle products in Akeneo and import them into Adobe Commerce. 

While Akeneo currently does not support bundle products as a built-in feature, you can achieve the desired functionality by creating a family, attributes, and options. Follow this tutorial for step-by-step guidance.

It is very important to respect the labels and codes so that the connector can correctly create the bundle.

 

1 - Create family, attributes groups and attributes

Create the family

Add a new family named "Bundle" with the code bundle. The family code will be used to determine if the product is a bundle, the family code name MUST BE bundle in lower case. For now this family can contain only few attributes: Name, SKU, Meta title, Meta description.

Create attribute groups

Add 2 Attribute groups: "Bundle Settings" with the code bundle_settings and "Bundle Options" with the code bundle_options.

Create attributes

Create 3 new attributes associated with "Bundle Settings" attribute group (The code for attributes and options MUST BE as indicated, in lower case):

Label Code Type Options
Ship Bundle Items shipment_type Simple Select
Label Code
Together 0
Separately 1
Dynamic Price price_type Yes/No  
Dynamic Weight weight_type Yes/No  

Create 2 new attributes associated with "Bundle Options" attribute group (The code for attributes and options MUST BE as indicated, in lower case):

Label Code Type Options
Bundle Options bundle_options Table > Empty table
Label Code Type Options
Option option Select
Label Code
Option 1 option_1
Option 2 option_2
Option 3 option_3
Option 4 option_4
Input Type input_type Select
Label Code
select select
radio radio
checkbox checkbox
multi multi
Title title Text  
Position position Number  
Required required Yes/No  
Code code Text  
Bundle Products bundle_items Table > Empty table
Label Code Type Options
Product item Select
Label Code
Product 1 product_1
Product 2 product_2
Product 3 product_3
Product 4 product_4
SKU sku Text  
Default Quantity selection_qty Number  
Is Default is_default Yes/No  
User Defined selection_can_change_qty Yes/No  
Price selection_price_value Number  
Price Type selection_price_type Select
Label Code
fixed fixed
percent percent
Option Code option_code Text  

 
 
 

2- Add all bundle attributes to the "bundle" family

  • Ship Bundle Items (shipment_type) 
  • Dynamic Price (price_type) 
  • Dynamic Weight (weight_type) 
  • Bundle Options (bundle_options) 
  • Bundle Products (bundle_items)
 
 

3 - Add a new product with the family "bundle"

To seamlessly import bundles, it's essential to configure your settings to reflect the following product configuration:

  1. First, add your options and define a free code. 
  2. Then, add products with the option code you want to attach the product to.

The product SKU must have been imported into Magento, otherwise it will not be associated with the option in Adobe Commerce.

 

When the bundle is ready in Akeneo, launch the Connector product job.

 
 

 

Non-covered product types

If you have some "custom" product type in Adobe Commerce, such as "Gift Cards". Those products don’t exist in Akeneo PIM,  those products will not be removed after synchronization. Akeneo Connector for Adobe Commerce keeps products that already exist in Adobe Commerce.

Regenerate URL rewrites

Since the 102.6.0 version of the Akeneo Connector for Adobe Commerce, if this configuration is set to Yes per default and whenever the url_key of a product changes, the connector will automatically generate a 301 redirect from the old URL to the new URL.

Within the connector configuration, under the "Products" section, you have the option to regenerate URL rewrites for Adobe Commerce products. This functionality allows you to efficiently manage and update the URL rewrites associated with your products in Adobe Commerce. This redirect serves to efficiently guide users from the previous URL to the updated one, ensuring a smooth and uninterrupted browsing experience. This enhancement helps maintain SEO rankings and provides a more user-friendly interaction with your e-commerce website.

Connector parameter title Connector default options
Regenerate URL rewrites Yes or No

Warning: By default, setting this option to "No" will result in a 404 error for any URL change.

This feature is configurable because some customers may use additional modules that handle URL key generation. If no such modules are in place, we recommend setting this option to "Yes" to ensure a smooth user experience. Otherwise, setting it to "No" will cause a 404 redirect for any URL change, which may negatively impact the user experience.

 

Map a specific attribute to generate the URL-key

The default URL-KEY is generated on the SKU. If you need the URL key to be based on another attribute, map the attribute in the attribute mapping section.

Attribute mapping section

Akeneo mapping Adobe Commerce mapping
attribute code name url_key
This attribute code  is a default one of Adobe Commerce and should not be changed.

Find my products on Adobe Commerce

To find your products in Adobe Commerce :

  1. Open Adobe Commerce CATALOG menu
  2. Click on Products

All product types are displayed together.

Find my product associations on Adobe Commerce

To find your product associations in Adobe Commerce :

  1. Open Adobe Commerce CATALOG menu
  2. Click on Products
  3. Use the search engine to find your product
  4. Open your product
  5. In Related Products, Up-Sells, and Cross-Sells you will find product associations related to your product.

Want to find out more? Take a look at these related articles