Elastic Path Synonym Sets API

openapi: 3.2.0
info:
  title: Catalog Search Introduction Synonym Sets API
  version: 26.0604.7696948
  x-version-timestamp: 2026-06-04 10:33:46+00:00
  description: 'Elastic Path Catalog Search provides fast, relevant product search capabilities for your published catalogs. Catalog Search enables shoppers to find products quickly using full-text search, filtering, faceting, and sorting, while giving merchandisers powerful tools to customize search relevance and ranking.


    You can integrate Catalog Search into your storefront using the Catalog Search API or manage search settings through Commerce Manager.


    ### How Catalog Search Works


    Catalog Search works alongside your Product Experience Manager catalogs to provide optimized search functionality.


    When creating or updating a catalog, enable search to allow the catalog''s products to be indexed. See [Catalogs](/docs/api/pxm/catalog/catalogs). Then when a search-enabled catalog is published, the products are automatically indexed for search. The search index contains product data optimized for fast querying.


    Use the Search API to query products with full-text search, filtering, faceting, and sorting. The results of the search contain the full product information, not just the indexed fields, reducing the need for further API calls.


    ### Key Capabilities


    - **Full-text search**: Search across product names, descriptions, SKUs, and custom fields with typo tolerance and relevance ranking

    - **Filtering**: Narrow results using conditions on product attributes, categories, prices, and custom fields

    - **Faceting**: Get aggregated counts for attribute values to build dynamic navigation and refinement options

    - **Sorting**: Order results by price, name, custom fields, or relevance score

    - **Search Profiles**: Configure search behavior including field weights, filters, and boost rules without code changes

    - **Custom Fields**: Extend the search schema with your own product attributes for filtering, faceting, and sorting

    - **Fully Hydrated Responses**: Search results contain complete information about the products, reducing the requirement for follow-up API calls.


    ### Personalized Search Results


    Search results are automatically personalized based on the shopper''s context. The system determines which catalog and prices to show based on:


    - **Channel**: The shopping experience, such as a web storefront or mobile app

    - **Account**: For B2B scenarios, the shopper''s account and any parent accounts

    - **Customer**: The logged-in customer''s segment or tier

    - **Tags**: Custom context tags for advanced segmentation scenarios


    See [**Characteristics of Shopper Catalogs**](/docs/api/pxm/catalog/shopper-catalog-api#characteristics-of-shopper-catalogs) for more information.


    ### Search Profiles


    Search Profiles give merchandisers control over search behavior without requiring code changes. With Search Profiles, you can:


    - **Configure field weights**: Control which product fields are most important for relevance ranking

    - **Apply default filters**: Enforce business rules like only showing live products

    - **Boost products**: Promote featured products, specific brands, or categories to the top of results

    - **A/B test**: Create multiple profiles to test different search configurations


    See [**Search Profiles**](/docs/api/pxm/catalog-search/search-profiles) for more information.


    ### Extending the Search Schema


    By default, the search index includes standard product fields like name, description, SKU, and categories. You can extend the schema by adding custom fields using [Indexable Fields](/docs/api/pxm/catalog-search/indexable-fields).


    Two types of custom fields can be indexed:


    - **Product extension fields** (`extensions.products(<slug>).<field>`): Fields from your product extension templates.

    - **Product custom attributes** (`shopper_attributes.<attribute>` and `admin_attributes.<attribute>`): Merchant-defined key/value attributes on products.


    This allows you to:


    - Search on custom product attributes like brand, material, or specifications

    - Filter products by custom fields like color, size, or rating

    - Display facets for custom field values in your navigation

    - Sort results by custom numeric fields like rating or popularity


    See [**Indexable Fields**](/docs/api/pxm/catalog-search/indexable-fields) for more information.

    '
servers:
- url: https://euwest.api.elasticpath.com/v2
  description: EU west cluster
- url: https://useast.api.elasticpath.com/v2
  description: US east cluster
security:
- BearerToken: []
tags:
- name: Synonym Sets
  description: '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 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](/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")

    '
paths:
  /pcm/catalogs/search/synonym-sets:
    post:
      tags:
      - Synonym Sets
      operationId: createSynonymSet
      summary: Create synonym set
      description: Create a new synonym set.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSynonymSetRequest'
      responses:
        '201':
          description: Successfully created synonym set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymSetResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Synonym Sets
      operationId: listSynonymSets
      summary: List synonym sets
      description: List all synonym sets.
      responses:
        '200':
          description: Successfully listed synonym sets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSynonymSetsResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /pcm/catalogs/search/synonym-sets/{synonym_set_id}:
    parameters:
    - name: synonym_set_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique ID of the synonym set
      example: 550e8400-e29b-41d4-a716-446655440000
      x-go-name: SynonymSetID
    get:
      tags:
      - Synonym Sets
      operationId: getSynonymSet
      summary: Get synonym set
      description: Get a synonym set by ID.
      responses:
        '200':
          description: Successfully retrieved synonym set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymSetResponse'
        '404':
          description: Synonym set not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Synonym Sets
      operationId: updateSynonymSet
      summary: Update synonym set
      description: Update a synonym set by ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSynonymSetRequest'
      responses:
        '200':
          description: Successfully updated synonym set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SynonymSetResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Synonym set not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Synonym Sets
      operationId: deleteSynonymSet
      summary: Delete synonym set
      description: Delete a synonym set by ID. A synonym set cannot be deleted while it is being used by any search profile.
      responses:
        '204':
          description: Synonym set marked for deletion
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - synonym set is referenced by a search profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    SynonymSetItem:
      type: object
      required:
      - id
      - synonyms
      properties:
        id:
          type: string
          description: Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.
          pattern: ^[a-zA-Z0-9_-]+$
          example: footwear-terms
          x-go-name: ID
        synonyms:
          type: array
          description: List of synonym terms.
          items:
            type: string
          minItems: 1
          example:
          - sneakers
          - trainers
          - running shoes
        root:
          type: string
          description: Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.
          example: jacket
        locale:
          type: string
          description: '[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.

            '
          example: en
        symbols_to_index:
          type: array
          description: Symbols to index for this synonym item. Each element must be exactly one character.
          items:
            type: string
            minLength: 1
            maxLength: 1
          example:
          - '-'
          x-go-type-skip-optional-pointer: true
    SynonymSetType:
      type: string
      description: Represents the type of object being returned. Always `catalog_search_synonym_set`.
      example: catalog_search_synonym_set
      enum:
      - catalog_search_synonym_set
    ResourceOwner:
      description: The resource owner, either `organization` or `store`.
      type: string
      example: organization
      enum:
      - organization
      - store
      x-go-type: tenancy.Owner
      x-go-type-import:
        path: gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    CreateSynonymSetRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              $ref: '#/components/schemas/SynonymSetType'
            attributes:
              $ref: '#/components/schemas/SynonymSetAttributes'
    UpdateSynonymSetAttributes:
      type: object
      properties:
        name:
          type: string
          description: Human-readable name for the synonym set.
          example: Apparel terms
        items:
          type: array
          description: The synonym items in this set.
          items:
            $ref: '#/components/schemas/SynonymSetItem'
          minItems: 1
    SynonymSetMeta:
      type: object
      required:
      - created_at
      - updated_at
      - owner
      - sync_status
      properties:
        created_at:
          type: string
          format: date-time
          description: The date and time the synonym set was created.
          example: '2026-03-05T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: The date and time the synonym set was last updated.
          example: '2026-03-05T12:00:00Z'
        owner:
          $ref: '#/components/schemas/ResourceOwner'
        sync_status:
          type: string
          description: The sync status of the synonym set.
          enum:
          - pending_sync
          - synced
          - sync_failed
          - pending_delete
          example: pending_sync
          x-go-type: model.SyncStatus
          x-go-type-import:
            name: model
            path: gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model
        last_synced_at:
          type: string
          format: date-time
          description: The date and time the synonym set was last successfully synced.
          example: '2026-03-05T12:01:00Z'
    UpdateSynonymSetRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - id
          - type
          - attributes
          properties:
            id:
              type: string
              format: uuid
              example: 8fccaa19-dba9-4621-8d11-31a222a68c7c
              x-go-name: ID
            type:
              $ref: '#/components/schemas/SynonymSetType'
            attributes:
              $ref: '#/components/schemas/UpdateSynonymSetAttributes'
    ListSynonymSetsResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SynonymSet'
        meta:
          $ref: '#/components/schemas/ListResponseMeta'
    SynonymSetResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/SynonymSet'
    ListResponseMeta:
      type: object
      required:
      - results
      properties:
        results:
          $ref: '#/components/schemas/ListResponseMetaResults'
    Error:
      required:
      - status
      - title
      properties:
        status:
          type: string
          description: The HTTP response code of the error.
          example: '500'
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
            - e7d50bd5-1833-43c0-9848-f9d325b08be8
    SynonymSetAttributes:
      type: object
      required:
      - name
      - items
      properties:
        name:
          type: string
          description: Human-readable name for the synonym set.
          example: Apparel terms
        items:
          type: array
          description: The synonym items in this set.
          items:
            $ref: '#/components/schemas/SynonymSetItem'
          minItems: 1
    ListResponseMetaResults:
      description: Contains the results for the entire collection.
      type: object
      required:
      - total
      properties:
        total:
          description: Total number of results for the entire collection.
          type: integer
          example: 100
    SynonymSet:
      type: object
      required:
      - id
      - type
      - attributes
      - meta
      properties:
        id:
          description: The unique identifier for the synonym set.
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
          x-go-name: ID
        type:
          $ref: '#/components/schemas/SynonymSetType'
        attributes:
          $ref: '#/components/schemas/SynonymSetAttributes'
        meta:
          $ref: '#/components/schemas/SynonymSetMeta'
  responses:
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                - title: Internal Server Error
                  status: '500'
  securitySchemes:
    BearerToken:
      scheme: bearer
      type: http