We recommend using Synonyms instead of Substitute Words to associate words with products, as synonyms allow you to manage terms per product in a more scalable way. Contact our Support team for more information.

There are two ways to set up synonyms in VTEX Admin: individually or by importing a spreadsheet in CSV format. If you need to register synonyms in bulk, we recommend using the spreadsheet. See the instructions for each configuration form in the following sections.

The configuration of synonyms works recursively. This means that when you add a second synonym to an existing one, it will also become a synonym for the first one.

Synonyms should not be used to resolve misspellings, plural and singular errors, or even pronouns, articles, and propositions in the search terms. On all these points, VTEX Intelligent Search is able to interpret, learn and solve them automatically through algorithms.

Follow the step-by-step procedure to configure synonyms individually in the VTEX Admin:

1. In the VTEX Admin, go to Storefront, or type Storefront in the search bar at the top of the page.
2. Under Intelligent Search, click Synonyms.
3. Click on Create Synonym.
4. Fill in the fields that correspond to the synonym:
   • Type: defines the type of synonym. Check Types of synonyms for more information.
   • Terms: words or expressions to be defined as synonyms. You must press Enter after each term to insert another term.
   • Locales: Languages to which the synonym will apply. The field is only available for stores using Multilanguage settings (Beta).
   • Status: defines whether the synonym will be active or inactive.
5. To finish, click on Save.

Changes can take up to two hours to take effect.

This feature is available on VTEX Intelligent Search Multilanguage. Read our article VTEX Intelligent Search: Multilanguage settings (Beta)to learn more.

In case there are many synonyms to be added, you can make a .csv file and import it in the Admin.

To import the file, follow the steps below:

1. Create a CSV file in the format described on Synonyms spreadsheet template.
2. In the VTEX Admin, go to Storefront, or type Storefront in the search bar at the top of the page.
3. Under Intelligent Search, click Synonyms.
4. Click on Import.
5. Drag the CSV file into the bounded area or click on choose a file to select the file on your device.
6. Click on Import.

The file must contain the following format, according to the types of synonyms chosen:

• Unidirectional: {terms separated by comma};{equivalent term};{status}

  Examples:

  • smartphone;iphone;true: When searching for smartphone, iphone results will be returned. However, when searching for iphone, smartphone results will not be returned.
  • tablet;ipad;true: When searching for tablet, ipad results will be returned. However, when searching for ipad, tablet results will not be returned.

• Bidirectional: {terms separated by comma};{status}

  Examples:

  • tv,television,television set;true: When searching for any of these terms, the products containing any of them will be returned.
  • monitor,screen,display;true: When searching for any of these terms, the products containing any of them will be returned.

Multilanguage stores (Beta)

Stores using Multilanguage settings (Beta) must follow the template below to import synonyms for specific locales.

• Unidirectional: {terms separated by comma};{equivalent term};{status};{locales separated by comma}

  Example:

  • smartphone;iPhone;true;en-GB: When searching for smartphone in the English language store (locale en-GB), the website will return results for iphone. However, when searching for iphone, the website will not return results for smartphone.

• Bidirectional: {terms separated by comma};{status};{locales separated by comma}

  Example:

  • tv,smart tv;true;en-GB: When searching for one of these terms in the store in English (locale en-GB), the search results will return any product that contains one of these terms.

If the imported .csv file does not have the locale, the synonym will be valid for all languages available in the store.