Product families

​

What is a product family?

A product family is a named group of products that should be treated as variations of the same item for merchandising purposes. The most common use case is grouping color variants, material variants, or regional variations of the same style. This way, a collection page shows a broader assortment instead of six near-duplicate rows of the same style. Product families are a building block for other features:

• Diversity expressions cap how many products from the same family appear in the top of a collection.
• Interaction block strategies treat family members as one product when computing behavioral recommendations, so colorways of the same style are not recommended alongside each other.
• Future family-aware merchandising features reuse the same groupings.

A product can belong to at most one family of each family type. The only family type today is canonical, which represents “this is the same underlying product.”

​

Publication status

Every manual product family has a publication status that controls whether the family is active for downstream features like Diversity expressions. You move a family between these states using the Publish and Unpublish buttons in the family editor. Automatic attribute-driven families do not have a publication status; they are active whenever the source attribute produces at least two products with the same value.

​

How status affects merchandising

• Draft families are ignored by Diversity expressions and any future family-aware feature. Their members behave as if they had no family assignment.
• Active families are applied everywhere product families are referenced. Unpublishing an active family is the fastest way to temporarily remove its effect without deleting member assignments.

​

Non-viewable members

If a member product is filtered out of your searchable catalog, it stays in the family and is marked with a red Not Viewable badge in the family editor. This can happen when the product is hidden in Shopify, excluded by a tag filter, or otherwise removed from storefront results. The product remains assigned to the family so the grouping is preserved if it becomes viewable again. While the badge is showing, the product doesn’t appear in storefront results, so features that consume product families (such as Diversity) effectively ignore it. Remove the product from the family if it should no longer be part of the group.

​

How families are created

Layers supports three sources for a family: Manual families always win. If a product is assigned to a manual family and its automatic attribute value later changes, the manual assignment is preserved.

​

Automatic families from an attribute

You configure which attributes drive automatic families in Settings → Product Families. Each entry points at a single attribute whose value will be used as the family key. Layers supports three kinds of attributes as family sources:

• Direct product fields and nested keys — for example, vendor, a style code metafield, or a named tag.
• Computed attributes — any computed attribute. The attribute is evaluated per product and its return value becomes the family key. The function can return a plain value, a metaobject reference, or a list of references.
• Metafields — Shopify metafields synced into your catalog, including reference types like metaobject_reference, list.metaobject_reference, and list.product_reference.

​

Combined listing groups

If your catalog contains Shopify combined listings, the attribute picker includes a Combined Listing Group option. Selecting it groups each combined-listing parent and its child products into one family. You don’t need a metafield or computed attribute to encode the relationship; Layers derives the grouping from the combined-listing data it already syncs. The option only appears when your store has at least one combined-listing product. When configuring family sources through the MCP server, use the attribute code combined_listing_group_id.

​

Reference and list attributes

When the selected attribute holds a reference instead of a plain value, Layers resolves it before grouping:

• Metaobject references key the family by the referenced object’s handle, and the family takes the metaobject’s display name instead of the Auto: <attribute>:<value> label. Renaming the metaobject in Shopify renames the family without moving any products between families.
• List attributes (like list.metaobject_reference or list.product_reference) contribute a single deterministic entry per product, because a product can only belong to one canonical family. Layers sorts the list’s resolved keys and picks the first, so reordering the list in Shopify does not move products between families. Only changing the list’s membership can.

​

How automatic assignment works

1. Layers reads the configured attribute for each product during catalog sync.
2. If the value is non-empty, the product is assigned to a family named Auto: <attribute>:<value>. Products sharing the same value land in the same family. Reference-valued attributes use the referenced object’s display name as the family name instead.
3. If the value is empty or missing, the product is removed from any automatically assigned family for that attribute.
4. Families that become empty are cleaned up automatically.

Automatic families are read-only in the Product Families dashboard. Edit the underlying attribute value to change membership. Saving changes in Settings → Product Families triggers a backfill, so new or removed sources apply to your existing catalog without waiting for the next product sync.

​

Prerequisites

Before you can configure automatic family sources, the attribute you want to use must already exist and be synced into your catalog. See Attributes and Metafields to add one. Computed attributes appear in the attribute picker with their compile status. An attribute labeled (not compiled) groups no products until its function compiles successfully.

​

Manual families

Manual families are fully editable in the dashboard. A manual family has:

• A name you choose (for example, Heritage Tee - All Colors).
• A publication status (Draft or Active) that controls whether the family is applied to merchandising features.
• A list of member products. Drafts can contain a single product while you assemble the group; active families must contain at least two unique products.

When you add a product to a manual family that was previously in an automatic family for the same family type, the product is moved. Manual CRUD wins.

​

Creating a manual family

See the step-by-step guide at Create a product family.

​

Editing and deleting

• Manual families can be renamed, have members added or removed, and can be deleted individually or in bulk from the Product Families list.
• Automatic families cannot be edited or deleted from the dashboard. To change their membership, update the attribute values on your products. Automatic families disappear on their own when they have no remaining members.

​

Bulk actions

From the Product Families list you can select multiple manual families and delete them in a single action. Automatic families in the selection are skipped because they remain under sync control.

​

Cross-references

Inside a collection’s sort order, a Diversity expression pairs with product families to cap how many near-duplicates appear in the top window. See:

• Diversity expressions
• Create a product family
• Automatic families from metafields
• Attributes
• Computed attributes