Work with synonyms

  • Updated

Synonyms allow your customers flexibility and variation when searching for products on your website. As an example, you offer several types of bubblers on your website, but they are not all called bubblers. Some are called water fountains, some are drinking fountains and others are referred to as fountains. The goal is to make sure when customers search for any of these variations, they are all returned in the search results.

Configured Commerce supports two types of synonyms: Bidirectional and Synonym.

Synonyms are not case-sensitive.

Bidirectional Synonyms

When there's many similar products that have slight name variations, like with the bubbler example, it is best to use a bidirectional synonym. When using bidirectional synonyms, search substitutes all of the listed synonyms for any of the terms a customer searches or when the system indexes the product's data.

In the bubbler example, searching Configured Commerce for water fountain produces products with the terms water fountain, drinking fountain, fountain or bubbler. This configuration also produces results for partial matches since the system indexes synonyms as a string. So, searching for "water" additionally surfaces products that include terms within this synonym string.


If you think your customers might search for a term, but you know your data reliably represents that term in other ways, use a uni-directional synonym. For example, if you know none of the products in your catalog are called "bubbler," but you know some customers may search for this term when looking for water fountains or drinking fountains, set up a uni-directional synonym for "bubbler."

If your data uses abbreviations not commonly searched by customers, set up a synonym with the abbreviation, for example "ELLB," as the synonym. Indicate "elbow" as the replacement token for this so that the system replaces all searches for "ELLB" with "elbow," both in queries and the index. Then if a user searches for "elbow," they will get the results they need.

The synonyms configuration has a number of notable exceptions:

  • Avoid configuring single-character synonyms
  • Avoid creating dimensional synonyms (for example, in=inch or .5=1/2)
  • Avoid creating synonyms only valid for a single or small number of products (such as competitive part numbers). Instead, Optimizely recommends adding this data to the product itself and ensuring it is indexed.
  • Avoid creating over 1,000 synonym records as there can be performance implications. If you approach this number, review the use cases with your partner for a more performant approach.

When creating synonyms, each Synonym relationship must be its own record. You can do this manually, by adding the various relationships into the list, or, if the number or relationships is lengthy, you may want to create the relationships in an Excel spreadsheet and then import it into the Synonyms list.

The best way to get the synonym import file is to create an export. You can click the export icon on the Admin Console > Marketing > Search > Synonyms page. Alternatively, an export file that you can modify to import your synonyms is attached at the bottom of this article. Please note that the Language column is obsolete and you can leave it blank.

Create synonyms

To provide context for the instructions below, recall the bubbler scenario above. The goal here is to make sure when a customer searches for any variants of bubbler, they all are returned in the search results.

  1. Go to Admin Console > Marketing > Search > Synonyms.
  2. Click Add Synonym.
  3. Set the Bidirectional toggle to Yes if this synonym should replace any synonym found with all synonym values. Unidirectional synonyms replace any synonym found with all replacement tokens.
  4. Click the Add Synonym icon to enter your synonyms.
IMPORTANT: You must rebuild all indexes after updating Synonyms. Go to Marketing > Search > Indexing in the Admin Console and click Rebuild All.

Using the steps above and referring to the provided scenario, the following table illustrates what would need to be included in the Synonyms list to satisfy the scenario:

Synonym Synonym Bidirectional
Bubbler water fountain Yes
Bubbler drinking fountain Yes
Bubbler fountain Yes