Skip to content

Importing and Exporting Groups

Linked Products imports and exports Linked Product Groups as CSV, one row per group. Files use SKUs and attribute codes, never database IDs, so you can export groups from staging and import them into production, or build groups for a whole catalog in a spreadsheet. Groups are a regular Magento import and export entity, Linked Product Groups, so they use the standard System → Data Transfer screens, Import History, and any tooling built on Magento's import framework. The bin/magento commands run the same import and export for large catalogs and automation.

The Linked Products CSV Format

A Linked Products CSV file has a header row and exactly three columns:

linked-product-groups.csv
group_name,skus,link_attributes
"Summer Tee","TEE-RED|TEE-BLUE|TEE-GREEN","color"
"Winter Boots","BOOT-38|BOOT-39|BOOT-40","size,color"
  • group_name - the import key. Group names are unique. A name that already exists replaces that group's products and link attributes. A new name creates a group. Matching ignores case, so bags beta updates a group named Bags Beta.
  • skus - the group's product SKUs, separated by |.
  • link_attributes - attribute codes, separated by ,. Quote the field when it holds more than one code. Only attributes that can link products are accepted, see Which Attributes Can Link Products.

A UTF-8 byte order mark is accepted, so a file saved from Excel as CSV UTF-8 imports as-is. On the Import screen, Download Sample File next to the entity gives you an example file.

Spreadsheet-Safe Exports

On export, a cell that starts with =, +, -, or @ gets a leading single quote, so spreadsheet software treats it as text instead of a formula. The importer strips that quote again, so an export, edit, and import round trip changes nothing. Other tools will see the quote.

Exporting Linked Product Groups from the Admin

You can export groups in two ways:

  • System → Data Transfer → Export, with Entity Type set to Linked Product Groups, exports every group. Like every Magento export, it is queued: the file appears in the list below the form once the exportProcessor message queue consumer has run.
  • Export to CSV in the Linked Product Groups grid's Actions menu exports the ticked groups, or every group that matches the current filter when you use Select All. It downloads the file right away, as does the CLI export.

Importing Linked Product Groups from the Admin

To import groups:

  1. Go to System → Data Transfer → Import.
  2. Set Entity Type to Linked Product Groups.
  3. Choose an Import Behavior:
    • Add/Update sets each named group's products and link attributes to exactly what its row lists, and creates groups that don't exist yet.
    • Delete deletes every group named in the file. The skus and link_attributes columns are optional then. Groups not named in the file are left alone.
  4. Choose your file under Select File to Import.
  5. Click Check Data. Nothing is saved yet.
  6. Read the validation results, then click Import.

Linked Product Groups on the Import page

Check Data lists errors and warnings with the rows they apply to, and notices such as products being moved from another group. The import reports how many groups it created, updated, and deleted, and every import from the admin is recorded in System → Data Transfer → Import History.

Import validation results

Importing requires the Import permission of Magento's Data Transfer ACL resources, plus Linked Product Groups create/edit for Add/Update or delete for Delete.

Moving Products Between Groups

A product belongs to one group at most. When a row lists a SKU that is already in another group, Add/Update moves the product into the imported group and reports it as a notice. The group the product leaves keeps its other products, however few, and is never deleted.

An import doesn't require a minimum number of products: a row can create or leave a group with one product or none. The group form only saves groups with at least two products, so such a group stays in the grid until you add products to it or delete it.

Importing and Exporting Linked Product Groups from the CLI

The CLI commands run the same import and export without the web server's time and upload limits, which makes them the better choice for large catalogs and deployment scripts.

# Export every group to a file, or to stdout when no file is given
bin/magento hyva:linked-products:export var/export/linked-product-groups.csv

# Validate a file without saving anything, like Check Data
bin/magento hyva:linked-products:import var/import/linked-product-groups.csv --dry-run

# Import with Add/Update, the default
bin/magento hyva:linked-products:import var/import/linked-product-groups.csv

# Delete the groups named in the file
bin/magento hyva:linked-products:import var/import/linked-product-groups.csv --behavior=delete

The export file name must end in .csv. The export won't overwrite an existing file unless you add --force. The CLI prints every finding of a run, including warnings and notices.

Linked Products CSV Validation Rules

The importer never applies part of a row: each row is either written in full or skipped.

Situation Outcome
Missing group_name Error, the row is skipped
group_name longer than 255 characters Error, the row is skipped
The same group_name twice in the file Error, the later row is skipped
Row without exactly three columns Error, the row is skipped
Unknown SKU Warning, the SKU is dropped from the row
SKU listed twice in the same row Warning, the SKU is used once
SKU already claimed by an earlier row in the file Error, the SKU is left out of this row
SKU already in another group Notice, the product is moved into this group
Unknown attribute code, or an attribute that can't link products Warning, the code is dropped from the row
Two codes for the same attribute Warning, the second code is dropped
Products on the storefront with the same option for every link attribute Warning naming the products and values, the row is still imported
Write failure in the middle of a row The row is rolled back and skipped, the cause goes to the exception log

The shared-values warning applies the same rule as the unreachable marks: it compares option values, not their labels, so two options both labelled Red are told apart, and it leaves out products that aren't on the storefront at the default scope (disabled, Not Visible Individually, or in no website).

Warnings Without Errors on Check Data

Magento's Import page lists a file's findings only when it has at least one error. For a file with warnings and no errors, Check Data shows File is valid! and, from Linked Products, the product-move notices and the shared-values warnings. Run bin/magento hyva:linked-products:import <file> --dry-run to see every warning, such as an unknown SKU.

Linked Products CSV Limits

Linked Products sets no row or file size limit of its own. The import framework reads the file in bunches instead of all at once, so the limits are Magento's upload size on the Import page and PHP's upload settings. Use the CLI for files larger than those allow.