Elastic Path Synonym Sets API

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 WorkA 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 TypesEach 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 ConfigurationEach 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 StatusSynonym 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 |### TenancySynonym 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 storeStores cannot modify organization-scoped synonym sets.### Using Synonym Sets in Search ProfilesSynonym sets only take effect once they are attached to a [search profile](/docs/api/pxm/catalog-search/search-profiles) 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")