Synonyms tools

list_synonyms_user: List the synonyms created by your team.
list_synonyms_br_generated: List the automatically generated synonym suggestions.

list_synonyms_user

Lists the synonyms your team has created by hand. Synonyms expand search recall by mapping terms that shoppers treat as equivalent. For example, mapping sneakers to shoes returns the same results for either term.

Synonyms can be one-way, where the source term maps to the target but not the reverse, or grouped, where every term in the group is treated as equivalent. This tool returns user synonyms account-wide by default, or scoped to a site through site_group_id. For automatically generated suggestions, use list_synonyms_br_generated.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, zero-based. Defaults to `0`. Use `-1` to fetch all synonyms in one request.
`limit`	`int`	No	The number of results per page. Defaults to `10`.
`sort_by`	`str`	No	The field to sort by. Defaults to `LAST_MODIFIED_DATE`.
`sort_order`	`str`	No	The sort direction, `ASC` or `DESC`. Defaults to `DESC`.

Response parameters

The tool returns a SynonymsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[SynonymSummary]`	The synonyms in the account.
`error`	`str \| null`	Error message if the request failed.

The SynonymSummary object has the following fields:

Field	Type	Description
`id`	`int`	The synonym's unique ID.
`merchantId`	`int \| null`	The merchant this synonym belongs to.
`sourceSynonym`	`str \| null`	The source term.
`targetSynonym`	`str \| null`	The target term.
`enabled`	`bool \| null`	Whether the synonym is enabled.
`groupSynonym`	`bool \| null`	Whether this is a group (bidirectional) synonym.
`synonymType`	`str \| null`	The synonym type, such as `USER_CREATED`.
`lastModifiedDate`	`int \| null`	Unix timestamp of when the synonym was last modified.
`lastModifiedBy`	`str \| null`	The user who last modified the synonym.
`siteGroupId`	`int \| null`	The site group ID. A `null` value means account-wide.

list_synonyms_br_generated

Lists the synonym suggestions generated automatically from observed search behavior. The AI identifies terms that shoppers use interchangeably, based on their queries and clicks, and proposes them as synonyms. Merchandisers can then review, enable, or disable each suggestion.

The response gives you paginated synonym summaries. For synonyms your team created by hand, use list_synonyms_user.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, one-based. Defaults to `1`.
`per_page`	`int`	No	The number of results per page. Defaults to `10`.
`sort_by`	`str`	No	The field to sort by. Defaults to `lastModifiedDate`.
`sort_order`	`str`	No	The sort direction, `Asc` or `Desc`. Defaults to `Desc`.

Response parameters

The tool returns a SynonymsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[SynonymSummary]`	The automatically generated synonyms.
`error`	`str \| null`	Error message if the request failed.

The SynonymSummary object has the following fields:

Field	Type	Description
`id`	`int`	The synonym's unique ID.
`merchantId`	`int \| null`	The merchant this synonym belongs to.
`sourceSynonym`	`str \| null`	The source term.
`targetSynonym`	`str \| null`	The target term.
`enabled`	`bool \| null`	Whether the synonym is enabled.
`groupSynonym`	`bool \| null`	Whether this is a group (bidirectional) synonym.
`synonymType`	`str \| null`	The synonym type, set to `BR_GENERATED_SITE`.
`lastModifiedDate`	`int \| null`	Unix timestamp of when the synonym was last modified.
`lastModifiedBy`	`str \| null`	The user who last modified the synonym.
`siteGroupId`	`int \| null`	The site group ID.