Variants

Summary

The Variants module in Supplier Data Manager (SDM) groups similar products so they can be pushed to Akeneo PIM as product models and their variant children. This article covers the interface, grouping rules, and configuration options for admins and integrators.

This module does not assume that a specific "parent" row exists in the input file. The parent is created automatically when products are grouped.

Interface and use cases

For an end-user walkthrough, see the dedicated guide.

The top of the Variants module screen shows clickable stat filters with four groups:

Rows to add in product model (red): rows that still have to be processed. The step cannot be finalized if rows remain in this group.
Rows added in product model (green): rows that have been manually grouped by a user.
Independent rows: rows marked as having no parent — these are pushed as simple products to the PIM.

The screenshot above shows the Variants module interface in Supplier Data Manager, displaying the stat filter bar at the top (with red, green, and independent row counts) and the two-panel table layout: the left table lists ungrouped products grouped by product model candidates, and the right table lists product models created by the user.

Below the filters, two tables appear side by side. The left table shows all products matching the current filter, grouped by product model candidate. It includes a Group column indicating which products can be grouped into a product model. The right table lists product models that have already been created.

Grouping products in the Variants module

The screenshot above shows the "Create a product model" popup in the Variants module, with fields for the product model ID, variant columns selection, and parent row selection.

To group products in the Variants module, select multiple ungrouped products from the left table and click Create a product model. A popup opens with the following fields:

Product model ID: Used internally to identify which products belong together. This value is stored in the attribute defined by product_model_name_column and is also used as the product model ID when pushing to Akeneo PIM.
Variant columns: The attributes whose values are allowed to differ between variant children. Attributes not marked as variant will share the value of the parent row.
Parent row: One row must be selected as the parent. All attributes not marked as variant will be set to the parent row's values when the step is finalized.

The screenshot above shows the product grouping validation state in the Variants module, highlighting how SDM checks matching groups before allowing product model creation.

Grouping validations

When grouping products, SDM runs validations based on the matching_groups configuration:

If allow_product_model_without_matching_group is disabled, SDM checks that all products being grouped have a matching group.
SDM checks that all products being grouped belong to the same matching group — if not, the creation or update is rejected.
Based on the matching group, SDM checks that the unique_columns all have different values. For example, SDM cannot group two blue, size L t-shirts if unique_columns are only size and color.

Automated grouping

The Variants module also supports automatic grouping via the automation setting in the connector configuration. When enabled, products are grouped automatically based on configurable grouping_columns values without manual intervention. See the automation keyword in the connector setup page for details.

Configuration

The Variants module configuration is managed in the Akeneo connector, not in a standalone SDM configuration screen.

How the Variants module works with the Akeneo connector

Project creation

By default, the Akeneo connector does not enable variants — set use_variants to true to activate them. Enabling use_variants does the following:

Changes the family hierarchy from one level (families only) to two levels (families and their variant families as children).
Adds a dedicated Variant step to the project. Without use_variants, the project uses a standard Akeneo step structure:

The screenshot above shows the standard Akeneo connector project step structure without variants enabled.

With use_variants enabled, the project structure becomes:

The screenshot above shows the expanded Akeneo connector project step structure with variants enabled, including the dedicated Variant step.

The reason for this more complex structure is to avoid duplicate work:

SDM first works only on variant attributes for products that have a family variant assigned. This limits the attribute set and prevents filling shared attributes more than once.
The Variant step is then automatically configured to output only parent and independent rows. Subsequent steps work only on simple products or product models.
From that point, SDM processes all remaining attributes.

The Variant step is fully configured by the connector. The matching_groups entry is built to represent variant families. SDM does not distinguish between variant families with one or two variation axes — everything is flattened to a single level and reconstructed during the push to Akeneo PIM. Each family variant is configured as a matching group with the following properties:

name: ID of the family variant
label: Translations of the family variant
conditions: Rules that check the family_variant attribute is not empty and matches the family variant ID
unique_columns: All variation axes from both levels. We support the same attribute types as variant axes as in the PIM.
variant_columns: All variant attributes from both levels
invariant_columns: Empty list

When the configuration is generated, variation axes are marked as required even if a max_requirement_level is set. SDM automatically forces these values to be filled because Akeneo PIM will reject the push if a variation axis is empty.

Project configuration updates

When a configuration sync is triggered for a connector, the Variant step configuration is automatically updated. SDM keeps the matching_groups entry up to date to correctly validate created groups.

If use_variants is active in the connector, a configuration sync will trigger an error if there is not exactly one Variant step in the project.

Pushing to Akeneo PIM

When a job completes and a connector is linked to the workflow with PIM push enabled, SDM pushes products in the following stages:

SDM pushes simple products directly.
SDM identifies all products marked as parent and pushes them as product models. The product model ID is the value the user entered when creating the group.
For variant families with two variation axes, SDM randomly selects one parent for each unique set of first-axis values. SDM then creates an intermediary parent that carries the first-axis attributes. The intermediary parent ID is the original parent ID concatenated with the first-axis values. For example, if t-shirts vary by color then size and the parent ID is tshirt-collection-aw25, the intermediary parent for blue t-shirts across all sizes would be tshirt-collection-aw25-blue.
SDM creates all children as products linked to the appropriate parent (first or second level, depending on the family variant).

Main differences from standard PIM product models

SDM supports Akeneo PIM product models, but the data model is handled differently in SDM's configuration and UI:

SDM displays two levels of variants, even when an intermediary level is present in the PIM.
SDM cannot update intermediary levels unless the specific naming convention described above is followed. To ensure the correct naming is applied automatically, create or recreate the product models through SDM.

Configuration example

Below is a sample variant_params as generated by the Akeneo connector (with one matching group for readability).

{
  "export_data": [
    "parent",
    "child",
    "independent"
  ],
  "output_data": [
    "parent",
    "independent"
  ],
  "matching_groups": [
    {
      "name": "fam_bathroom_sink_variant_1",
      "label": {
        "fr-FR": "Vasque - Forme, couleur"
      },
      "conditions": [
        {
          "name": "required",
          "field": "family",
          "negate": false
        },
        {
          "name": "isin",
          "field": "family",
          "negate": false,
          "values": [
            "fam_bathroom_sink"
          ]
        },
        {
          "name": "required",
          "field": "family_variant",
          "negate": false
        },
        {
          "name": "isin",
          "field": "family_variant",
          "negate": false,
          "values": [
            "fam_bathroom_sink_variant_1"
          ]
        }
      ],
      "unique_columns": [
        "product_shape",
        "product_color"
      ],
      "variant_columns": [
        "parcel_send_to_effitrace",
        "product_CBM",
        "product_PVR_TTC_PCS",
        "product_PVR_TTC_PCS-currency",
        "product_color",
        "product_depth",
        "product_depth-unit",
        "product_description_instructions-fr_FR",
        "product_diameter",
        "product_diameter-unit",
        "product_ean",
        "product_from_prestashop",
        "product_height",
        "product_height-unit",
        "product_origin_description",
        "product_origin_image_url",
        "product_origin_informations",
        "product_origin_name",
        "product_supplier_reference",
        "product_suppliers_purchase_price_per_pcs",
        "product_suppliers_purchase_price_per_pcs-currency",
        "product_variant_name-fr_FR",
        "product_weight",
        "product_weight-unit"
      ],
      "invariant_columns": []
    }
  ],
  "variant_columns": [],
  "default_id_column": "code_modele",
  "invariant_columns": [],
  "product_model_head_column": {
    "name": "is_parent",
    "label": {
      "fr": "est un parent"
    }
  },
  "product_model_name_column": {
    "name": "akeneo_parent_id",
    "label": {
      "fr": "Akeneo parent id"
    }
  },
  "allow_product_model_without_matching_group": false
}

For reference, the corresponding variant family as configured in the client's PIM:

{
    "code": "fam_bathroom_sink_variant_1",
    "labels": {
        "fr_FR": "Vasque - Forme, couleur"
    },
    "variant_attribute_sets": [
        {
            "axes": [
                "product_shape"
            ],
            "level": 1.0,
            "attributes": [
                "product_name",
                "product_styles",
                "product_summary",
                "product_seo_description",
                "product_height",
                "product_width",
                "product_depth",
                "product_diameter",
                "product_weight",
                "product_shape",
                "product_instruction_file",
                "product_installation_vid",
                "product_schema_pics",
                "product_description",
                "product_main_points",
                "product_long_name",
                "product_description_instructions",
                "product_syphon_diameter"
            ]
        },
        {
            "axes": [
                "product_color"
            ],
            "level": 2.0,
            "attributes": [
                "sku",
                "product_step_of_publication",
                "product_is_dropshipped",
                "parcel_send_to_effitrace",
                "product_color",
                "product_origin_name",
                "product_origin_description",
                "product_supplier_reference",
                "product_CBM",
                "product_suppliers_purchase_price_per_pcs",
                "product_packshot_pics",
                "product_ambience_pics",
                "product_zoom_pics",
                "product_influencers_pics",
                "product_trace_file",
                "product_PVR_TTC_PCS",
                "product_ean",
                "product_variant_full_name",
                "parcel",
                "product_origin_informations",
                "product_origin_image_url",
                "product_from_prestashop",
                "product_reverse_full_name",
                "product_variant_name",
                "product_total_parcel_qty",
                "product_reverse_variant_name_2"
            ]
        }
    ]
}

Key observations from this example:

output_data includes parent and independent only, ensuring SDM fills all necessary attributes without duplicating work on children.
The variant family has two variation axes (product_shape at level 1, product_color at level 2), which are combined into a single matching group in SDM.
default_id_column is set to code_modele because the input file already contains the product model name.

Glossary

Parent products: A product model with only common (non-variant) attributes. Parent products cannot be purchased. One parent may be linked to many child products.
Child products: Purchasable products that carry variant attributes (the attributes that differ between children). Each child is linked to a parent product.
Independent products: Products with no product model attached and no variation — also called simple products. All fields in an independent product are common attributes.

Akeneo Help Center