Skip to main content

Product Variations

Where to find it: Admin → Products → Custom Fields

When you'd use this: Use this when you sell products with multiple attribute variations (like door handles in different finishes and backplate styles, or furniture in different fabrics and leg finishes) and want customers to switch between variants on the product detail page.

What you need first:

  • Products that belong to the same range or family
  • Clear attribute categories that differentiate the variants (e.g., Finish, Backplate, Size)

Set it up:

  1. Create a custom field with type ItemGroup to define your product range or family (e.g., "Charleston", "Federal", "Haven")
  2. Create custom fields with type ItemGroupAttribute for each varying attribute:
    • Name the attribute followed by its value (e.g., "Finish: Brass", "Backplate: Oval")
    • Repeat for each combination (e.g., "Finish: Aluminium", "Finish: Black")
  3. Assign the same ItemGroup value to all products in the range
  4. Assign the relevant ItemGroupAttribute values to each product variant
  5. The system automatically groups and links products during catalog indexing

How it works:

When a customer views a product detail page, the system displays swatches grouped by attribute type. For example, viewing "Charleston - Brass - Oval" shows:

  • Finish swatches: Brass (current), Aluminium, Black
  • Backplate swatches: Oval (current), Rounded, Square

Each swatch links to the corresponding product variant. The current product's attributes are highlighted. The system only displays swatches for attributes with available product combinations.

When you update a product's ItemGroup or ItemGroupAttribute values, the system automatically updates the swatches for all related products in the same group during the next catalog index. This ensures all products in a group reflect the latest available variants.

Troubleshooting:

  • Swatches aren't appearing for a product — Verify the product has both an ItemGroup value and at least one ItemGroupAttribute value assigned. Products with empty or null values won't be included in the grouping.
  • A variant is missing from the swatches — Check that the missing variant has the same ItemGroup value as the other products in the range and that all its ItemGroupAttribute values are populated.
  • Swatches aren't updating after changing a product — Changes to ItemGroup or ItemGroupAttribute values require a catalog reindex to take effect. The system automatically includes all products in the same group when indexing, so swatches stay synchronized across related products.