Synonyms API

Manage synonym groups — the same entities the Synonyms screen edits. All endpoints require authentication and the Magento_Search::synonyms ACL resource.

Synonym object

Field	Description	Type	Required
group_id	Unique group identifier	Int	Read-only
synonym_group	Comma-separated list of terms, for example shoes,footwear,sneakers	String	Yes
store_id	Store view the group applies to; 0 means all store views	Int	No
website_id	Website the group applies to; 0 means all websites	Int	No

---

Get synonym group

GET /rest/V1/mst-search/synonyms/:groupId

Response:

{
  "group_id": 2,
  "synonym_group": "zorblat,duffle,satchel,tote",
  "store_id": 1,
  "website_id": 0
}

Errors: 404 — no group with that ID.

---

List synonym groups

GET /rest/V1/mst-search/synonyms?searchCriteria

Supports filtering and pagination.

Response:

{
  "items": [
    {
      "group_id": 2,
      "synonym_group": "zorblat,duffle,satchel,tote",
      "store_id": 1,
      "website_id": 0
    }
  ],
  "search_criteria": { "filter_groups": [], "page_size": 2 },
  "total_count": 1
}

---

Create synonym group

POST /rest/V1/mst-search/synonyms

Request body:

{
  "synonym": {
    "synonym_group": "zorblat,duffle,satchel",
    "store_id": 1,
    "website_id": 0
  }
}

Response: the created group with group_id assigned.

Errors: 409 — the terms overlap an existing group in the same scope. See Merge conflicts.

---

Update synonym group

PUT /rest/V1/mst-search/synonyms/:groupId

This is a partial update: only the fields present in the body are applied, so omitting store_id or website_id leaves the group's scope as it was.

Request body:

{
  "synonym": {
    "synonym_group": "zorblat,duffle,satchel,holdall"
  }
}

Response: the updated group.

Errors: 404 — no group with that ID. 409 — the new terms overlap another group in the same scope.

---

Delete synonym group

DELETE /rest/V1/mst-search/synonyms/:groupId

Response:

true

Errors: 404 — no group with that ID.

---

Merge conflicts

A synonym group whose terms already appear in another group in the same scope is a conflict. By default nothing is stored and the request is refused with 409:

{
  "message": "Merge conflict with existing synonym group(s): (zorblat,duffle,satchel) Repeat the request with \"mergeOnConflict\": true to merge them instead."
}

This is the same default as the admin form, where Merge existing synonyms is unchecked. To merge the overlapping groups into one — the behaviour of that checkbox — repeat the request with merge_on_conflict:

{
  "synonym": {
    "synonym_group": "duffle,tote",
    "store_id": 1,
    "website_id": 0
  },
  "merge_on_conflict": true
}

The response is the single merged group, which carries a new group_id and the union of the terms:

{
  "group_id": 2,
  "synonym_group": "zorblat,duffle,satchel,tote",
  "store_id": 1,
  "website_id": 0
}

note

A synonym write affects storefront search results immediately — no cache flush and no reindex. With Fast Mode enabled, autocomplete is the exception; see the write contract.