Instructions for Combining products into variations

The add-on groups separate products into standard CS-Cart variation groups by the common part of their SKU. The SKU processing rule is assigned separately to each variant of the selected brand feature. Grouping can be started manually from the add-on settings or automatically through cron.

What the add-on does

When the process starts, the add-on finds products that use a variant of the selected brand feature with a grouping format assigned. It calculates a grouping key for each SKU according to that format. If at least two products have the same key, the add-on creates a variation group through the standard Product Variations functionality.

If one of the matching products already belongs to a variation group, the add-on adds the other matching products to that group. Products with an empty SKU, without an assigned format, or with the “Do not combine” format are skipped.

Where to find the add-on

• Add-ons → Downloaded add-ons → Combining Products into Variations → Settings — select the brand feature, set the security key, start grouping manually, and copy the cron command.
• Products → Features → selected brand feature → Variants — set Product combination format for each feature variant.
• Products → Products — open processed products and check the standard variation groups.

Before the first run

The add-on relies on the standard Product Variations functionality. Prepare the items as separate products, fill in their SKUs, and assign a brand feature variant to every product that should be processed. Make sure the selected products can be combined with the standard Product Variations tools: the add-on delegates group creation and extension to them and does not override their restrictions.

Configure the add-on

1. Select the brand feature

1. Open the add-on settings.
2. In Brand feature, select the active extended feature whose variants are assigned to products as brands.
3. Save the settings.

The list contains active extended features only and displays their internal names. The Product combination format field is shown only for variants of the feature selected in the add-on settings. If the selected feature is later disabled or deleted, a run ends with a message that the brand feature is unavailable.

The Start product grouping button appears in the settings after a feature is selected. The generated command in the Cron link block is displayed after the security key is filled in.

2. Assign a format to each brand variant

1. Go to Products → Features.
2. Open the feature selected in the add-on settings.
3. For each required brand variant, select a value in Product combination format.
4. Save the feature.

The format defines which part of the SKU is treated as variable. After that part is excluded, the remainder becomes the grouping key.

Formats are assigned to brand variants, but the resulting group is determined by the calculated SKU key. Products from different brands may be placed in one group if they produce the same key. Use SKU patterns that prevent such overlaps.

If you select another feature in the add-on settings, processing uses only variants of that feature. Assign formats to variants of the new feature before the next run; formats saved for the previously selected feature are not used in that run.

3. Set the security key

1. Fill in Security key in the add-on settings. Replace the default value with your own long random string.
2. Save the settings.
3. Copy the generated command from the Cron link block.

The cron command sends a hash of the key in the --hash parameter, not the key itself. Do not publish the generated command because it authorizes a grouping run. If the command is exposed or the key is changed, save a new key and copy the newly generated command.

Run grouping manually

1. Make sure the brand feature is selected and formats are assigned to the required variants.
2. In the add-on settings, click Start product grouping.
3. Wait for a CS-Cart notification. After a successful run, it reports the number of products combined.

One run processes all catalog products that have a non-empty SKU and a variant of the selected feature with a format assigned. The add-on does not provide a separate filter by category, product status, vendor, or storefront. In Multi-Vendor and Ultimate, account for this catalog-wide scope before running the process. A group is created only when at least two products produce the same key.

Schedule automatic grouping with cron

1. Copy the entire command from the Cron link block in the add-on settings.
2. Add it to the cron scheduler on the store server.
3. If necessary, change only the schedule at the beginning of the line. Keep the PHP command, path, --dispatch=ms_combining_options.combine parameter, and generated --hash unchanged.

The generated command runs every day at 04:00 server time and starts with 0 4 * * *. It already contains the PHP CLI version, the path to the store root, and the customer-facing script name. Use the command generated for the current store.

How to check the result

1. Select one brand feature variant and assign the Last two characters format to it.
2. Prepare two test products with that feature variant and the SKUs MODEL-01 and MODEL-02.
3. Start grouping manually.
4. Check the successful processing notification.
5. Open either test item under Products → Products and make sure both products are in the same standard variation group.
6. Add a control product with a different key or the Do not combine format and verify that it is not added to this group.

Important notes for repeated runs

• The add-on creates new groups and adds products to existing groups, but it does not split or delete groups that already exist.
• Changing the format assigned to a brand variant does not undo a previous run. Correct an unwanted group with the standard Product Variations tools.
• At least two products must have exactly the same calculated key.
• An empty SKU, a missing hyphen for the corresponding rule, or an invalid dot-separated structure causes the product to be skipped.
• Check that keys are unique across brands: the brand value itself is not added separately to the grouping key.

Common messages and checks

• Brand feature is not set. Select a feature in the add-on settings and save the changes.
• The brand feature is not found or is not enabled. Make sure the selected feature exists and is active, or select another active extended feature.
• No products with an eligible combination format were found. Assign formats to variants of the selected feature and make sure those variants are assigned to products.
• Not enough products were found. Check the SKUs: after the rule is applied, at least two products must have exactly the same key.
• Products were not combined. Check the SKU structure, existing groups, and whether these products can be combined with the standard Product Variations tools.
• The cron command no longer starts processing. If the security key changed, copy the new command. Also check that the specified PHP CLI version is available and that the cron user can run the store's customer-facing script.