Introduction

Product Compatibility lets you declare which products fit together, such as a windshield and the vehicles it fits, with a single rule instead of manual links on every product. The PIM then automatically resolves that rule across your whole catalog and keeps the result up to date as products change.
 

What is Product Compatibility

Product Compatibility, also called fitment, defines which products and Product Models work with one another. Instead of recording compatibility product by product, you create a new Automatic association type which contains a selection of primary products, a selection of compatible products, and optional conditions that match them by Attribute value.

The PIM resolves that rule dynamically, rather than storing a fixed, hand-picked list like a manual Association Type does. Your compatible products stay current: when a product that matches your selection is added, it appears in the list, and when a product is deleted, it disappears.

If you sell car parts, you can replace fitment data entered on every windshield and every vehicle with one rule: a windshield fits a vehicle when the vehicle's windshield reference matches the windshield's glass code. The PIM then works out the matches for every windshield and vehicle in your catalog.

The same logic applies to a TV and the wall mounts it fits, a soundbar and a TV, winter tires and the wheel diameters they fit, or bedside tables and the headboards from the same collection.

Key benefits

• Define compatibility once: write one rule based on Attribute values instead of maintaining individual links on every product. A single rule can cover an unlimited number of product pairs, and you can edit it after setup.
• Stay accurate as your catalog evolves: matches are recalculated when products are added, updated, or removed, so fitment data never drifts from the product data it depends on.
• Reuse the result anywhere: compatibility appears in the Product Edit Form, can be filtered in the product grid, and is available through the REST API for your commerce platform, marketplaces, and other connected systems.
  
   

Locate compatibility in your settings

Go to Settings > Association types. From there, you can create two kinds of Association Type:

• Manual associations: unidirectional (1-way), bidirectional (2-way), or quantified. You pick each associated product yourself.
• Automatic associations: the compatibility rules described in this article. The PIM computes the matches for you.

Understand how a compatibility rule works

A compatibility rule is made of a primary product selection, a compatible product selection, and an optional set of conditions.

• Selections can be refined with filters on System Properties or on regular Attributes from your PIM. Product Models are supported and appear in the selection when you use a hierarchy filter that includes them in the first or the second step.
• Conditions are optional. Without conditions, every product in the primary selection is compatible with every product in the compatible selection. A product is never matched with itself.
• Conditions are grouped. Conditions inside the same group are combined with AND or OR. With ALL, one empty value on the primary product means no compatible product at all. With ANY, an empty value is ignored and the other conditions decide. An empty value on the compatible side never matches.
• Records of Reference Entities can be selected and matched, as well as the Attributes of those records.
• Operators cover equality and numeric ranges.
• Direction: a new rule is 2-way (Bidirectional) by default, so the match appears on both Product Edit Forms. You can switch it to 1-way (Unidirectional) in the Properties tab of the rule.

For example, for every Desk Chair in the Modernists collection from Season 2026, you can link the matching Armrests from the same collection and season. With a 2-way rule, matching Armrests appear on the Desk Chair page, and matching Desk Chairs appear on the Armrests page.
 

Attribute types you can use in conditions

Create a compatibility rule

1. Go to Settings > Association types and create a new Automatic association.
2. Enter a label and a code.
3. In Step 1, Primary products, choose the product selection the rule starts from, for example a Family or a more targeted selection with its own filters.
4. In Step 2, Compatible products, choose the product selection the primary products can be matched against.
5. In Step 3, Conditions, add the Attribute-based conditions that narrow down which primary products match which compatible products. Leave this step empty if any primary product should match any compatible product.
6. Check your Preview, with the ‘Preview’ button on the top right corner.
7. Click Save and Enable.

Every new rule, including a duplicate, is disabled by default, so nothing is exposed in your catalog until you enable it. To change the direction of the rule, open its Properties tab and switch between 1-way (Unidirectional) and 2-way (Bidirectional).
 

Preview of your Compatibility

Click Preview in the top-right corner to test your rule in real time. Select a primary product to check the logic and view the matching items, and switch products at any time to see different results across your catalog.

 

Duplicate a rule

Open the ... menu of an existing rule, next to Save and Enable or Save and Disable, then click Duplicate. A dialog opens with a prefilled code and label, suffixed with _copy and - copy.

Duplication is unavailable while you have unsaved changes on the rule you duplicate from and the copy is always created disabled.

Find compatibility results in the PIM

In the Associations tab of a product

Open a product and go to the Associations tab. Select the ‘Association type’ that you would like to check for the Compatibility. If a rule matches the product, you see the list of products it is compatible with, with one row per compatible product and per matching rule.

From that list, you can select one or more products and send them to an existing Association Type. 

This helps when several teams contribute to the assortment. For example, at an Electronics retailer, category managers let the rule build the full list of cases compatible with the iPhone 16, then e-merchandisers select the five best-selling cases and send them to the You might also like Association Type pushed to the website. 
Please note that you need to save the product before you leave the page.

 

In the product grid

With the ‘Associated with’ filter, you can select a product or a Product Model, then an Association Type, to list everything it is manually associated with. A variant also returns what its Product Model holds, as it does in the Product Edit Form, the API, and the exports.

Import and export compatibility rules

Export and import compatibility rules with your Association Types in CSV or XLSX format. Use these files to back up your rules, review or duplicate them in bulk, or copy them from one environment to another.

A single file can contain both compatibility rules and manual Association Types, with one row per Association Type.

Export a rule as a template

To prepare an import file, start with a rule built in the rule builder:

1. Create a compatibility rule in the rule builder.
2. Export your Association Types in CSV or XLSX format.
3. Use the exported row as a template and edit the codes and values you need.

The export includes every key of the rule, so you do not need to write the JSON structure from scratch.

Understand the file columns

Read the rule column

The rule column uses the same format as the rule object in the REST API. You can use the same structure for your import files and integrations.

Each key corresponds to a part of the rule builder:

Choose condition operators

Each condition compares a base_attribute on the primary product with a compatible_attribute on the compatible product.

Identify Attributes in a condition

Both base_attribute and compatible_attribute use these keys:

Import compatibility rules

When you import Association Types, the PIM reads the rule cell in each row:

• A JSON object creates or updates a compatibility rule. The PIM applies the same validation checks as the rule builder and the API.
• An empty cell identifies a manual Association Type. You cannot use an empty cell to convert an existing compatibility rule into a manual Association Type.

Fix skipped rows

The import skips a row and displays a warning in the following cases:

Understand what files do not cover

• Association Type exports contain the rules, not their results. To retrieve compatible products, use the REST API as described in the article's Retrieve compatibility through the API section. See the API reference for Products and Product Models.
• Product imports cannot set compatibility. The PIM computes compatibility from the rule, so you cannot add compatibility links manually through a product import. A product file with a column such as <rule_code>-products causes the import to fail.

Limitations

• Both sides of a condition must use the same Attribute type. A number can only be compared with a number.
• The Contains operator cannot be used on a 2-way rule. The save is refused.
• For Measurements, both Attributes must belong to the same measurement family, for example length with length. Units are converted automatically, so 17 inches matches 43.18 cm.
• For Reference Entity Attributes, both sides must point to the same Reference Entity.
• Localizable and scopable Attributes are supported. You can choose a Channel and a Locale for the primary and/or compatible products.
• Unsupported Attributes are greyed out in the dropdown selectors.
• Lists and grid filters stop displaying results beyond 10,000 products. The full list remains accessible through the API.
• Automatic associations (compatibility) reflect the current rules and product information whenever you view or retrieve them. Changes to these compatibility links do not trigger a product updated event on the Event Platform.
• These Attribute types cannot be used in conditions: Identifier, Text area, Price, Image, Table, File, Asset collection, and single Product link.
• Product Compatibility is currently not supported on our Apps.
• Each tenant is limited to 100 Compatibility rules. A rule can match an unlimited number of product pairs.
   

Retrieve compatibility through the API

The public REST API exposes compatibility results in read-only mode, and offers read and write endpoints for the rules themselves. An ERP, a PLM, or any other connected system can therefore create and maintain rules and query compatibility without using the user interface.

Choose the right way to link products

If you need to link products to each other, use this table to choose between a manual Association Type, Product Compatibility (for Automated Association), a Product link Attribute, and a Table Attribute with a Product link column.