Synonym Sets

Synonym Sets allow you to define groups of equivalent or related terms so that searches for one term also return results for its synonyms. This helps shoppers find products regardless of the specific terminology they use.

How Synonym Sets Work

A synonym set is a named container of synonym items. Each set belongs to an organization or store and is synced asynchronously. Once synced, a set can be attached to one or more search profiles; its synonym rules are then applied during searches that use those profiles to expand queries with matching terms.

Synonym Types

Each item within a synonym set can be either multi-way or one-way:

• Multi-way synonyms: All terms are treated as equivalent. Searching for any term in the list returns results for all of them. For example, ["sneakers", "trainers", "running shoes"] means a search for "trainers" also returns results for "sneakers" and "running shoes".
• One-way synonyms: Searches for a root term also match the synonyms, but not vice versa. For example, with root: "jacket" and synonyms: ["blazer", "coat"], searching for "jacket" also returns results for "blazer" and "coat", but searching for "blazer" does not return results for "jacket".

Synonym Item Configuration

Each item within a synonym set supports the following options:

Option	Required	Description
id	Yes	Unique identifier for the item within the set. Alphanumeric characters, hyphens, and underscores only.
synonyms	Yes	List of synonym terms. Minimum 1 if root is provided (one-way), minimum 2 if root is absent (multi-way).
root	No	Makes this a one-way synonym. Must not also appear in the synonyms array.
locale	No	ISO 639-1 language code for this item. Defaults to en. See Locale and Synonym Expansion below.
symbols_to_index	No	Special characters to preserve as part of tokens. Each element must be exactly one character.

Locale and Synonym Expansion

A synonym only expands a query when its locale matches the locale of the highest-weighted search field for that request. Omitting a locale is identical to setting en, so under a normal single-language configuration every synonym applies and no locale needs to be set.

Locale becomes significant when a catalog carries localized product text:

• A request with no Accept-Language header searches the catalog's global name and description, which are English. Synonyms with locale en — or none — expand.
• A request with Accept-Language: fr, against a catalog that has French name or description, promotes the French text above the global text. Only synonyms with locale fr expand; English ones do not. A French catalog therefore needs French synonym items.
• If a field that has no localized variant is weighted above name and description, that field's locale governs instead, so French synonyms do not expand even for a French request.
• A custom field configured with a locale governs every request when it is the highest-weighted field, including requests with no Accept-Language header.

Because the highest-weighted field decides this, changing search field weights can change which synonyms expand.

Sync Status

Synonym sets are synced asynchronously. The sync status is tracked and exposed in API responses:

Status	Description
pending_sync	Set has been saved but is not yet applied to the search cluster
synced	Set has been successfully synced
sync_failed	The last sync attempt failed
pending_delete	Set is marked for deletion; a background worker will remove it

Tenancy

Synonym sets follow the same tenancy model as other resources:

• Organization-scoped sets: Managed by the organization; apply across all stores
• Store-scoped sets: Managed by the store; apply only to that store

Stores cannot modify organization-scoped synonym sets.

Using Synonym Sets in Search Profiles

Synonym sets only take effect once they are attached to a search profile via its synonym_sets attribute. At search time, the synonym sets of the resolved search profile are applied to the query.

When attaching a synonym set to a search profile:

• The set must exist and be accessible by the calling tenant. Organization-level search profiles may only reference organization-level sets; store-level search profiles may reference organization-level and same-store sets.
• The set must have been synced at least once. A set in pending_sync or sync_failed state can still be used if it was previously synced — its last synced state continues to apply.

A synonym set cannot be deleted while it is referenced by any search profile; the delete request is rejected with a 409 Conflict until the reference is removed.

Use Cases

• Regional terminology: Map British and American English terms (e.g., "trousers" ↔ "pants")
• Brand equivalents: Link product category names with common alternatives
• Industry jargon: Ensure technical terms match colloquial ones
• Abbreviations: Map abbreviations to their full forms (e.g., "tee" → "t-shirt")

📄️ Create synonym set

Create a new synonym set.

📄️ List synonym sets

List all synonym sets.

📄️ Get synonym set

Get a synonym set by ID.

📄️ Update synonym set

Update a synonym set by ID.

📄️ Delete synonym set

Delete a synonym set by ID. A synonym set cannot be deleted while it is being used by any search profile.