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
rootterm also match thesynonyms, but not vice versa. For example, withroot: "jacket"andsynonyms: ["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 language code for this synonym item. |
symbols_to_index | No | Special characters to preserve as part of tokens. Each element must be exactly one character. |
Sync Status
Synonym sets are synced asynchronously. The sync status is tracked and exposed in API responses:
| Status | Description |
|---|---|
pending_sync | Set has been created or updated in MongoDB but not yet synced |
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_syncorsync_failedstate 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.