Using Synonyms

Shoppers describe the same product in different words. One searches for couch, another for sofa; one types sneakers, another trainers. Synonyms teach Catalog Search that these words mean the same thing, so a search for any of them finds all the matching products — even when the product data only uses one of the words.

Synonyms are organized into synonym sets. Each set contains one or more items, and each item defines a single synonym rule. You attach a synonym set to a search profile, and it applies to every search that uses that profile.

No reindexing required

Synonyms are applied when a search is executed, not when products are indexed, so you never need to reindex your catalog. Changes to a synonym set are synchronized to the search engine in the background and take effect within a few seconds.

One-Way and Multi-Way Synonyms

Each item in a synonym set is either multi-way or one-way, depending on whether it has a root.

Multi-Way (Equivalent) Synonyms

A multi-way item lists words that are all interchangeable — searching for any one of them finds products matching any of the others. A multi-way item has no root and needs at least two words.

{ "id": "seating", "synonyms": ["couch", "sofa", "settee"] }

With this item, a search for couch returns products named couch, sofa, and settee alike. So does a search for sofa or settee. Use multi-way items for true equivalents.

One-Way (Directional) Synonyms

A one-way item has a root. Searching for the root word also finds the listed synonyms, but not the other way around.

{ "id": "fruit-terms", "root": "fruit", "synonyms": ["apple", "mango", "peach"] }

With this item, a search for fruit (the root) returns products with apple, mango, and peach in their name (as well as any product named fruit). But a search for apple returns only apple products — it does not pull in mangoes or peaches. Use one-way items when a general term should broaden to include specific ones, but the specific terms should stay precise.

Item type	Example	Search couch/fruit finds	Search sofa/apple finds
Multi-way	synonyms: ["couch", "sofa", "settee"]	couch, sofa, settee	couch, sofa, settee
One-way	root: "fruit", synonyms: ["apple", "mango", "peach"]	fruit, apple, mango, peach	apple only

Quick Reference

Synonym sets are managed through the following endpoints, relative to your API base URL (for example https://useast.api.elasticpath.com/v2):

Operation	Method & Path
Create a synonym set	POST /pcm/catalogs/search/synonym-sets
List synonym sets	GET /pcm/catalogs/search/synonym-sets
Get a synonym set	GET /pcm/catalogs/search/synonym-sets/{synonym_set_id}
Update a synonym set	PUT /pcm/catalogs/search/synonym-sets/{synonym_set_id}
Delete a synonym set	DELETE /pcm/catalogs/search/synonym-sets/{synonym_set_id}

A synonym set has these attributes:

Attribute	Type	Required	Description
name	string	Yes	A human-readable name for the set.
items	array of synonym items	Yes	The synonym rules. Must contain at least one item.

Each entry in items has these fields:

Field	Type	Required	Description
id	string	Yes	Identifies the item within the set. Must match ^[a-zA-Z0-9_-]+$ and be unique within the set.
synonyms	array of strings	Yes	The interchangeable words. Multi-way items need at least two; one-way items need at least one.
root	string	No	Makes the item one-way. Searches for the root expand to the synonyms, but not the reverse. Must not appear in synonyms.
locale	string	No	The ISO 639-1 language code used to tokenize the item and to match it against fields of the same locale. See Locale Support.
symbols_to_index	array of strings	No	Special characters to preserve within a word (for example ["+"] so c++ is kept). Each element must be a single character.

Creating a Synonym Set

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search/synonym-sets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_synonym_set",
      "attributes": {
        "name": "Storefront synonyms",
        "items": [
          { "id": "seating", "synonyms": ["couch", "sofa", "settee"] },
          { "id": "fruit-terms", "root": "fruit", "synonyms": ["apple", "mango", "peach"] }
        ]
      }
    }
  }'

The response includes a generated id and a meta block with the set's synchronization state:

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "catalog_search_synonym_set",
    "attributes": {
      "name": "Storefront synonyms",
      "items": [
        { "id": "seating", "synonyms": ["couch", "sofa", "settee"] },
        { "id": "fruit-terms", "root": "fruit", "synonyms": ["apple", "mango", "peach"] }
      ]
    },
    "meta": {
      "owner": "store",
      "created_at": "2026-03-05T12:00:00Z",
      "updated_at": "2026-03-05T12:00:00Z",
      "sync_status": "pending_sync"
    }
  }
}

A new set starts with sync_status: pending_sync and must reach synced before it can be attached to a profile. See Synchronization Status. The set should synchronize within a few seconds.

Attaching a Synonym Set to a Search Profile

A synonym set has no effect until it is attached to a search profile. Add the set to the profile:

curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search-profiles/{profile_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_profile",
      "attributes": {
        "synonym_sets": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
      }
    }
  }'

A few rules apply to synonym_sets:

• A profile can reference multiple synonym sets; all of them are applied to searches using that profile.
• A set can only be attached to a search profile once it is synced to the search engine.

Once attached, updating the synonym set itself changes behavior for every profile that references it.

Synonyms are not applied to autocomplete

Synonym expansion applies to full search queries only. Autocomplete (search-as-you-type) queries are matched as typed.

Tuning Synonym Behavior

A profile's optional synonym_settings object controls how synonym matches are ranked and how query words are resolved against the attached synonym sets. Like the synonym sets themselves, these settings are applied at search time, so changing them never requires reindexing.

curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search-profiles/{profile_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_profile",
      "attributes": {
        "synonym_settings": {
          "demote_synonym_match": true,
          "synonym_resolution_allowed_on_prefix": false,
          "number_of_typos_allowed_when_resolving_synonyms": 1
        }
      }
    }
  }'

A few rules apply to synonym_settings:

• Every field is optional; each defaults as noted below.
• The settings only have an observable effect when the profile has synonym sets attached — they tune synonym behavior but do not create it.
• When updating a profile, the synonym_settings object is replaced as a whole, so include every setting you want to keep. To reset all synonym settings back to their defaults, update the profile with "synonym_settings": null.
• The settings do not apply to autocomplete queries, which never resolve synonyms.

Ranking Direct Matches Above Synonym Matches (demote_synonym_match)

By default (demote_synonym_match: false), a product matched directly and a product matched only through a synonym are ranked equally — their relevance scores are the same, so their relative order is left to the search engine's internal tie-break and is effectively arbitrary. Set demote_synonym_match: true to add a final tiebreaker that ranks directly matched products above synonym matches.

Because it is only a tiebreaker — the lowest-priority signal in textual relevance ranking — it never overrides stronger relevance signals. A highly relevant synonym match can still outrank a weak direct match; the flag only decides the order of results that are otherwise equally relevant.

Consider the multi-way set couch/sofa/settee, three products named couch, sofa, and settee, and a search for couch:

demote_synonym_match	Result order for couch
false (default)	All three score equally, so the order is arbitrary (for example settee, sofa, couch)
true	The directly matched couch is promoted to the top, followed by the sofa and settee synonym matches

{ "synonym_settings": { "demote_synonym_match": true } }

Resolving Synonyms on Partial Words (synonym_resolution_allowed_on_prefix)

By default (synonym_resolution_allowed_on_prefix: false), only a complete query word can resolve to a synonym. Set it to true to let an incomplete (prefix) query word resolve to a synonym as well.

This is not the same as the prefix setting. The prefix setting treats only the last word of the query as a partial word; synonym_resolution_allowed_on_prefix applies prefix matching at every word position when looking words up in the synonym sets — there is no last-word special-casing. An exact match always wins: a query word that exactly equals a synonym resolves regardless of this flag, and the prefix behavior only affects words with no exact synonym match.

Consider a synonym set with synonyms red ↔ burgundy, malus domestica ↔ apple, and apparel ↔ cloth, and synonym_resolution_allowed_on_prefix: true:

• red app — red matches exactly (it expands to burgundy); app is a prefix of both apple and apparel, so both expand to malus domestica and cloth respectively.
• re app — re is a prefix of red, and app is a prefix of apple/apparel, so every word expands. The regular prefix setting would only treat the last word (app) as a partial word; here every position is matched.

{ "synonym_settings": { "synonym_resolution_allowed_on_prefix": true } }

This composes with number_of_typos_allowed_when_resolving_synonyms (below), which governs typo tolerance during the same lookup.

Allowing Typos When Resolving Synonyms (number_of_typos_allowed_when_resolving_synonyms)

By default, a synonym expansion only triggers when a query word is spelled correctly. If a shopper misspells couch as counch, typo tolerance can still find the couch product, but the misspelling does not expand to sofa and settee. Set number_of_typos_allowed_when_resolving_synonyms to let misspelled words trigger synonyms too. Accepted values are 0 (default — synonyms only resolve on exactly spelled words), 1, or 2.

Consider a synonym set linking hammer and mallet, two products with those names, and the misspelled query hammar:

number_of_typos_allowed_when_resolving_synonyms	Search for hammar matches
0 (default)	hammer only — regular typo tolerance corrects the query, but the misspelling does not trigger the synonym
1	hammer and mallet — the misspelling also resolves through the synonym

{ "synonym_settings": { "number_of_typos_allowed_when_resolving_synonyms": 1 } }

This setting only affects synonym expansion. Regular typo tolerance (num_typos) still finds the directly matching product either way, and this setting is independent of the other typo_tolerance settings such as num_typos and typo_tokens_threshold.

Moved from typo_tolerance

number_of_typos_allowed_when_resolving_synonyms now lives under synonym_settings alongside the other synonym tuning options. It was previously part of the profile's typo_tolerance object.

Localization Support

Each item can carry a locale (an ISO 639-1 code such as en or fr). The locale serves two purposes:

• Tokenization. The item's root and synonyms are tokenized using the rules for that language, so they are split into words consistently with how text in that language is indexed. If not provided, the English tokenizer is used.
• Selecting which items apply. At search time, only the synonym items whose locale matches the locale of the search profile's highest-weighted field are used. If that field has no locale, only items with no locale are used.

The Highest-Weighted Field

The highest-weighted field is the field with the largest weight in the profile's fields array. If no weights are set, the first field listed in the profile is treated as the highest-weighted field.

Its locale only decides which set items are selected — it does not limit where they apply. Once resolved, the synonyms are applied across every field the profile searches, not just the highest-weighted one.

How Localized Fields Affect Selection

When a request includes an Accept-Language header and your products have localized name or description values, the search profile fields are expanded to locale-specific variants before searching. For each language that matches the request, a variant such as meta.locales.en-US.name is added ahead of the original field, keeping the same weight — so the localized variant becomes the highest-weighted field. (Only name and description are expanded this way as product name and description are the only fields that support localization.)

This is what determines the locale used to select synonym items:

• Localized search. When the shopper's language matches a localized field, the highest-weighted field is that localized variant, so synonym items whose locale matches the shopper's language are selected. For example, consider, if the product name is the highest-weighted field in the search profile. Furthermore, the products have French name defined. If the shopper searches in French, the French name will be the highest-weighted field and the search engine will only resolve synonyms where locale is also French.
• Non-localized search. When no localized variant applies — there is no Accept-Language header, or your products are not localized — the highest-weighted field is the plain name/description field, which has no locale, so only items with no locale are selected.

Set each item's locale to match the language your shoppers search in (and that your products are indexed in). A rule whose locale does not match the resolved field locale is never selected, even though the set is attached to the profile.

Preserving Special characters

By default, the search index strips special characters, so s24+ is indexed as s24. If a synonym depends on a symbol, list it in symbols_to_index so the engine keeps it:

{ "id": "cpp", "synonyms": ["c++", "cplusplus"], "symbols_to_index": ["+"] }

Each element of symbols_to_index must be a single character. This mirrors the tokenization settings used when indexing fields. Please note symbols_to_index must also be configured on the product fields to ensure synonyms actually match special characters in products when searching.

Updating a Synonym Set

You can update the name, the items, or both. Updating items replaces the entire list, so include every item you want to keep.

curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search/synonym-sets/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "catalog_search_synonym_set",
      "attributes": {
        "items": [
          { "id": "seating", "synonyms": ["couch", "sofa", "settee", "loveseat"] }
        ]
      }
    }
  }'

Changes return the set to pending_sync until synchronized. While the update is still pending, searches continue to use the set's previous synonyms, then switch to the new synonyms as soon as the change synchronizes. The set should generally sync within a few seconds after updating.

Deleting a Synonym Set

curl -X DELETE https://useast.api.elasticpath.com/v2/pcm/catalogs/search/synonym-sets/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A synonym set cannot be deleted while a search profile still references it.

Synchronization Status

Changes to synonym sets are propagated to the search engine asynchronously. The meta.sync_status field reflects where a set is in that process:

sync_status	Meaning
pending_sync	Created or updated, not yet propagated to the search engine
synced	Live; meta.last_synced_at is set. The set can now be attached to profiles
sync_failed	Synchronization did not complete; it is retried automatically

A set must reach synced state at least once before it can be used in a search profile.

Organization and Store Scope

Synonym sets are scoped to the tenant that creates them:

• Organization-scoped sets can be attached to organization and store search profiles.
• Store-scoped sets can be attached only to that store's profiles.

Validation and Errors

Status	When
400	items is empty, an item id has invalid characters or is duplicated, or locale is invalid
400	A multi-way item (no root) has fewer than two synonyms
400	A root value also appears in that item's synonyms
400	A symbols_to_index element is longer than one character
400	A profile's synonym_sets contains an invalid UUID, a duplicate, or a set that does not exist / has not synced
400	A profile's synonym_settings.number_of_typos_allowed_when_resolving_synonyms is greater than 2
403	A store tries to update or delete an organization-scoped set
404	The synonym set does not exist
409	The set is still referenced by one or more search profiles

Best Practices

1. Use multi-way for true equivalents, one-way for broadening. Words that mean the same thing (couch/sofa) belong in a multi-way item; a general-to-specific relationship (fruit → apple, mango, peach) belongs in a one-way item so specific terms stay precise.
2. Give items meaningful IDs. The item id identifies the rule when you update the set — footwear-terms is clearer than item1.
3. Wait for synced before attaching. A profile can only reference a set that has finished syncing.
4. Detach before deleting. Remove a set from every profile before deleting it, or the delete returns 409.

Related Resources

• Setting Up Catalog Search
• Using Stopwords
• Handling Typos
• Search Profiles API
• Catalog Search API Reference