Define Product Compatibility between products

Summary

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.
Association types settings with the create dropdown showing manual and automatic options

 

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.

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)
At least 1 match: one shared option. All match: the compatible product holds every option of the primary one

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

  1. Go to Settings > Association types and create a new Automatic association.
  2. Enter a label and a code.
  3. In Step 1, Entities to link, keep Products as the source and choose Products or a Reference entity as the target.
  4. 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.
  5. In Step 3, Compatible products (or Compatible records), choose the selection the primary products can be matched against.
  6. 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.
  7. Check your Preview, with the ‘Preview’ button on the top right corner.
  8. 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.

Product Associations tab listing compatible products returned by an automatic 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:

  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

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. 
If you omit this column, existing rules keep their direction and new rules are 2-way.

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>-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 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.

All API resources on ‘Product Compatibility’ are available here and here.

 

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.