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. A rule can also link products to the records of a Reference Entity, for example brake pads and the vehicles they fit when vehicles are managed as records rather than products. The PIM then automatically resolves that rule across your whole catalog and keeps the result up to date as products and records change.
This feature is available for Premium customers. Contact your CSM to learn more.
What is Product Compatibility
Product Compatibility, also called fitment, defines which items work with one another.
Instead of manually recording links product by product, you create a single Automatic Association Type that pairs a selection of primary products with a selection of compatible items based on Attribute values. The compatible side of your rule can target other Products and Product Models, or it can target Reference Entity records, which is ideal when the objects your products fit are not items you sell, such as vehicles, machines, equipment, or brands.
The PIM resolves that rule dynamically, rather than storing a fixed, hand-picked list like a manual Association Type does. Your compatible items stay current: when a matching product or record is added, it appears in the list, and when it 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.
🎓 Want an interactive walkthrough to go deeper?
Join our training to explore Product Compatibility, understand use cases, see how it works, and practice in a real test environment: Start the course.
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.

To learn more about manual Association Types, read Manage your association types.
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.
- The compatible selection can be products or the records of a Reference Entity. Conditions can read Attributes of the records linked to a product, or Attributes of the compatible records themselves. See Link products to Reference Entity 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. A rule that links products to records is always 1-way.
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.
Link products to Reference Entity records
You can link products to items you do not sell, such as vehicles, machines, or equipment models stored as Reference Entity records. A compatibility rule links your products directly to those records, so you do not need to create a product for each vehicle or machine.
Configure the rule
- In Step 1, Entities to link, the source is always Products and cannot be changed. You can select a Reference entity as the target, for example Reference entity: Vehicles.
- In the primary selection, filter the products you want to link, just as you would for a product-to-product rule.
- In the compatible selection, select records from the chosen Reference Entity. Filter them by record code with the Equals, Does not equal, or Contains operators, or by record Attributes, such as a model year of at least 2018. Code filters are case-insensitive.
- To check that your selection is what you expected, look at the number of records in the selection. Click View selection to see their images, labels, and codes.
- In Conditions, compare a product Attribute with a record Attribute, for example the product’s ‘axle width’ and the vehicle’s ‘axle width’. Attributes that cannot be compared are locked, with the reason displayed.
Example: select the products in the Brake pads Family and the records of the Vehicles Reference Entity, then add a condition that matches their axle width Attributes. When you open a brake pad, you see the vehicle records it fits.
Find compatible records
You have several options to find compatible records.
- In the Associations tab: open a product or a Product Model to see its compatible records, listed after the compatible products in the same table. Each record shows its image, label, code, and rule, and counts in the tab counter.
- In the Preview: select a product to see the records linked by the rule.
- With the search: in the Associations tab and in the Preview, you can search for records by code.
Understand the limitations
- You cannot select records or send them to a manual Association Type. Their checkboxes are disabled.
- A rule cannot start from records. Linking records to products, or records to other records, is not supported.
- For products to reference entity records links, the direction is always1-way (Unidirectional): the link appears on the product, and you cannot switch it to 2-way.
- In the product grid filter, it is not possible to view the compatible records.
Attribute types you can use in conditions
Attribute type |
Operators you can pick |
Can be compared with |
How values match |
|---|---|---|---|
Text |
Is equal to, Contains |
Text, Text area, Identifier, record Text Attribute |
Is equal to: same text. Contains: the compatible text contains the primary one |
Text area |
Is equal to, Contains |
Text, Text area, Identifier, record Text Attribute |
Same as Text, ignoring formatting. Only the first 10,000 characters count |
Identifier |
Is equal to |
Text, Text area, record Text Attribute |
Same value, for example a text field holding the SKU of the product it fits |
Yes/No |
Is equal to |
Yes/No |
Same value |
Number |
Is equal to, At least, At most |
Number, record Number Attribute |
Numeric comparison |
Measurement |
Is equal to, At least, At most |
Measurement of the same measurement family |
Units are converted first, so 1 m matches 100 cm |
Date |
Is equal to, At least, At most |
Date |
At least: same day or later. At most: same day or earlier |
Simple select |
Is equal to |
Simple select, Multi select, record option Attributes |
Same option code, even across different Attributes |
Multi select |
Exact match, At least 1 match, All match |
Multi select, Simple select, record option Attributes |
Exact match: both products hold the very same options, in any order (a product holding one additional option does not match) |
Reference Entity single link |
Is equal to |
Single or multiple links to the same Reference Entity |
Same record |
Reference Entity multiple links |
At least 1 match |
Single or multiple links to the same Reference Entity |
At least one shared record |
Record Text Attribute |
Is equal to, Contains |
Text, Text area, Identifier, record Text Attribute |
Same as Text, read on the linked record |
Record Number Attribute |
Is equal to, At least, At most |
Number, record Number Attribute |
Same as Number, read on the linked record |
Record single option Attribute |
Is equal to |
Simple select, Multi select, record option Attributes |
Same as Simple select, read on the linked record |
Record multiple options Attribute |
At least 1 match |
Simple select, Multi select, record option Attributes |
Same as Multi select, without All match |
Product link |
Is equal to |
Product link |
Same product or Product Model |
Create a compatibility rule
- Go to Settings > Association types and create a new Automatic association.
- Enter a label and a code.
- In Step 1, Entities to link, keep Products as the source and choose Products or a Reference entity as the target.
- In Step 2, Primary products, choose the product selection the rule starts from, for example a Family or a more targeted selection with its own filters.
- In Step 3, Compatible products (or Compatible records), choose the selection the primary products can be matched against.
- In Step 4, Compatibility Conditions, add the Attribute-based conditions that narrow down which primary products match which compatible products or records. Leave this step empty if any primary product should match any compatible item.
- Check your Preview, with the ‘Preview’ button on the top right corner.
- Click Save and Enable.



Exclude products from a selection
A selection can include products that should never appear in the results, for example a vehicle that matches the rule but uses a specific windshield, or a discontinued reference. To remove them, add a filter with an exclusion operator to your Primary products or Compatible products selection.
For example, to exclude specific references, add a filter on the Identifier with the Not in list operator and select the products to remove. These products are excluded from the selection, so they are never matched by the rule, even when they meet the conditions in Step 3.
In a selection of records, use the record code with Does not equal to remove specific records.
You can combine exclusion filters with your other filters to narrow down the selection as much as you need. Use the Preview to check the result before you save the rule.
In a selection of records, use the record code with the Does not equal operator to remove specific records.
Disable rules
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).
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.
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.

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.

Records linked by a rule are listed after the products. They cannot be sent to a manual Association Type.
The tab follows the locale and the channel selected in the Product Edit Form.
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.
This filter can be shared. Copy the grid link and anyone who opens it gets the same filtered view, without setting the filter up. Both filters also respect view permissions: a product a user cannot see never appears as a match for them.
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:
- Create a compatibility rule in the rule builder.
- Export your Association Types in CSV or XLSX format.
- 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
Column |
Description |
|---|---|
code |
Code of the Association Type. |
label-<locale> |
Label in each Locale, for example label-en_US. |
is_quantified |
1 for a quantified manual Association Type. Always 0 for a compatibility rule. |
is_two_way |
1 for a bidirectional (2-way) rule, or 0 for a unidirectional (1-way) rule. |
rule |
The compatibility rule as a JSON object. Leave this cell empty for a manual Association Type. |
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:
Key |
In the rule builder |
Content |
|---|---|---|
enabled |
Rule status |
true when the rule is enabled. If you omit this key, new rules are imported as disabled and existing rules keep their current status. |
base_product_selection |
Step 2, Primary products |
An operator (AND or OR) and a list of criteria. Each criterion is either a filter with a field, an operator, and a value, or a nested group with its own operator and criteria. |
compatible_product_selection |
Step 3, Compatible products |
The same structure as Step 1. |
| compatible_record_selection | Step 3, Compatible records | Use it instead of compatible_product_selection to link to records. It holds a reference_entity_code, an operator (AND or OR) and a list of criteria on the record code or on record Attributes. Groups of record criteria cannot be nested. |
condition_groups |
Step 4, Conditions |
An operator and a list of conditions. Use AND when all conditions must match, or OR when any condition can match. Conditions cannot be nested. |
A rule holds either compatible_product_selection or compatible_record_selection, never both.
In Step 2 and Step 3, you can nest groups up to 5 levels deep, with up to 25 entries per group.
Example of an import row that links brake pads to vehicle records:
code;label-en_US;is_two_way;is_quantified;rule
fits_vehicles;Fits vehicles;0;0;"{""enabled"":true,""base_product_selection"":{""operator"":""AND"",""criteria"":[{""field"":""family"",""operator"":""IN"",""value"":[""brake_pads""]}]},""compatible_record_selection"":{""reference_entity_code"":""vehicles"",""operator"":""AND"",""criteria"":[{""field"":""model_year"",""operator"":"">="",""value"":""2018"",""scope"":null,""locale"":null}]},""condition_groups"":{""operator"":""AND"",""conditions"":[{""base_attribute"":{""attribute_code"":""axle_width"",""scope"":null,""locale"":null},""operator"":""="",""compatible_attribute"":{""attribute_code"":""axle_width"",""scope"":null,""locale"":null}}]}}"
Choose condition operators
Each condition compares a base_attribute on the primary product with a compatible_attribute on the compatible product.
Operator in the file |
Operator in the rule builder |
|---|---|
= |
Is equal to |
>= |
At least |
<= |
At most |
contains |
Contains, for text Attributes on 1-way rules only |
matches_any |
At least 1 match |
matches_all |
All match |
matches_exactly |
Exact match |
Identify Attributes in a condition
Both base_attribute and compatible_attribute use these keys:
Key |
Description |
|---|---|
attribute_code |
Code of the Attribute to compare. |
scope |
Channel of a scopable Attribute. Use null otherwise. |
locale |
Locale of a localizable Attribute. Use null otherwise. |
record_attribute_code |
For a Reference Entity Attribute, the Attribute of the records to compare instead of the records themselves. Use null to compare the records. |
In these keys, null does not mean a value is missing. It means the setting does not apply to that Attribute.
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.
To import a rule as enabled, set "enabled": true in the rule cell. If you omit the enabled key when creating a rule, the rule is imported as disabled. If you omit it when updating an existing rule, its status remains unchanged: enabled rules stay enabled, and disabled rules stay disabled.
Fix skipped rows
The import skips a row and displays a warning in the following cases:
Why the row is skipped |
What to check or change |
|---|---|
The rule cell is not a valid JSON object. |
Check the JSON syntax in the cell. |
The rule refers to an unknown Attribute, or the Channel or Locale does not match the Attribute settings. |
Check the Attribute codes and whether each Attribute is scopable or localizable. |
The code belongs to a manual Association Type. |
Use a new code. A manual Association Type cannot become a compatibility rule, and a compatibility rule cannot become a manual Association Type. |
The rule cell is empty for an existing compatibility rule. |
Add the rule JSON or remove the row from the file. |
The import would create a 101st rule. |
Check the number of rules in your PIM. The limit is 100 rules per PIM, including disabled rules. |
| The rule holds both a product selection and a record selection on its compatible side. | Keep only one of them. |
| The Reference Entity code is unknown. | Check the reference_entity_code. |
| The primary side selects records. | A rule must start from products. |
| A group of record criteria is nested. | Flatten the record criteria. |
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>-productscauses 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 items, products and records alike. 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 (in the 1st and 2nd step): 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.
- Records of a Reference Entity a user may not view are hidden from that user, in the UI and in the API. A user without the permission to list Reference Entity records sees no records at all.
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.
The associations endpoints of products and Product Models also return the records a rule links to, as items with "type": "record", the reference_entity_code and the record code, ordered by record code. Association Types can be created and updated through the API with a compatible_record_selection, in the same format as the import file.
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.
|
Manual associations |
Compatibility |
Product link Attribute |
Table Attribute with a Product link column |
|---|---|---|---|---|
Question it answers |
What do we want to sell alongside this product? |
What does this product technically fit? |
Which single product goes with this one? |
Which products make up or complete this one? |
Key benefits |
Full manual control over the products selected, several types to break results down by usage, quantities with the quantified type, and a shareable Associated with filter in the product grid |
Automatic linking once the conditions are set up, no limit on the number of compatible products, and the ability to link to Reference Entity records, for objects you do not sell. |
Single product enforcement, visible in the Product Edit Form, can be localizable and scopable, and can count towards Completeness |
Additional information for every linked product, can be localizable and scopable, can count towards Completeness, and backlinks between products |
Where it is configured |
Settings > Association types, Manual |
Settings > Association types, Automatic |
Settings > Attributes, type Product link, then the Family |
Settings > Attributes, type Table with a Product link column, then the Family |
Where it is filled in |
Product Edit Form, Associations tab |
Nothing to fill in, results are computed from the conditions and shown in the Associations tab of every matching product |
Product Edit Form, in the Attribute field |
Product Edit Form, in the Table Attribute |
Nature of the data |
Stored, fixed matches between products |
Dynamic, recalculated as the catalog changes |
Stored as an Attribute value |
Stored as an Attribute value |
Extra data carried |
Quantity, with the quantified type |
None |
None |
Metadata columns: measurement, text, date, boolean |
New products covered automatically |
No |
Yes, when they match the rule |
No |
No |
Direction |
1-way, 2-way, or quantified |
1-way or 2-way |
1-way, with a backlink on the target |
1-way, with a backlink on the target |
Main limits |
A 2-way association links two products only |
Several Attribute types cannot be used in conditions: Identifier, Text area, Price, Image, Table, File, Asset collection, single Product link |
One product per Attribute value, and no metadata on the link |
100 Table Attributes per PIM, first column must be a select, a Reference Entity, an incremental number, or a Product link, duplicate entries allowed outside the first column, and lines removed automatically when a linked product is deleted |
Typical use case |
Cross-sell, up-sell, packs, you might also like |
Fitment: rims and vehicles, cases and phones, mounts and TVs, parts and machine records |
A camera and its charger, a handbag and its replacement strap |
A cosmetic product and the ingredients that are SKUs in the PIM |
Ready to try it? Create your first Automatic association in Settings > Association types, or contact your CSM to discuss your packaging and activate Product Compatibility.