Search synonyms

Manage locale-specific equivalent search terms for product discovery.

Search synonym groups expand recognized words or phrases to the alternatives in that group. Expansion is case-insensitive and scoped to the store and search language. Other query words, product visibility, and active filters still apply; equivalent terms do not guarantee identical ranking. Changes are read by new search requests without a synonym reindex.

Use GET /search-synonyms/locales to discover enabled languages for these groups. Reads require read_search; writes require write_search, which also grants read access. The token must be valid and the store must have an active or trialing subscription. Use Authentication, Rate limits, and Errors for the shared request rules.

Group response fields

A group has the following fields in list, create, and update responses. Create and update also return a top-level success code and message. All six endpoints return HTTP 200 on success.

Field	Type	Meaning
`id`	string	Group UUID. Always present.
`store_id`	string	Owning store UUID. Always present and resolved from the token.
`locale`	string	Enabled store language code. Always present; there is no wildcard group.
`terms`	array of strings	Complete set of 2–25 terms. Always present. Leading and trailing whitespace is removed, repeated spaces become one, and Unicode text is normalized. Case and order are preserved.
`created_at`	string	Creation time as an RFC 3339 timestamp, with fractional seconds when present. Always present.
`updated_at`	string	Last successful update time as an RFC 3339 timestamp, with fractional seconds when present. Always present.

Use the offset in each response timestamp; do not assume it matches the store timezone.

Webhooks and language removal

Subscribe to search_synonyms/create, search_synonyms/update, and search_synonyms/delete below when maintaining a copy. Each requires write_search for app subscriptions. The update event contains the resulting group; the delete event contains its deletion snapshot. Webhook payload timestamps are UTC and store_id is carried on the delivery envelope.

Removing a language from the store deletes its groups, without a separate group-delete event for each one. A mirror must also handle store/locales/deleted; adding the language again does not restore those groups. See Languages for the language-deletion event and its subscription requirements.

Endpoints#

List search synonym languages

GET read_search

List enabled languages for synonym groups.

Returns the enabled language codes, display labels, and default-language flag using Search read access. Use the returned locale code when creating or moving a group.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
The Authorization header is missing.
401 INVALID_TOKEN
The Bearer header or token prefix is malformed.
401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED
The token was not accepted: it is unknown, expired, revoked, or replaced, or its app was uninstalled. Returned for app, App Bridge session, and Store Admin tokens alike.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 API_VERSION_UNSUPPORTED
The credential is pinned to an API version that cannot be served.
429 RATE_LIMITED
The request allowance is exhausted. Wait for Retry-After before retrying.
403 STORE_API_SCOPE_REQUIRED
The token does not grant the required resource scope. A write_search grant also permits reads.

curl 'https://api-store.tringify.com/api/2025-01/search-synonyms/locales' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/search-synonyms/locales", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/search-synonyms/locales",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "locales": [
      {"locale": "en", "label": "English", "native_name": "English", "selector_label": "English", "rtl": false, "is_default": true, "created_at": "2026-07-01T10:15:00Z"},
      {"locale": "hi", "label": "Hindi", "native_name": "हिन्दी", "selector_label": "हिन्दी — Hindi", "rtl": false, "is_default": false, "created_at": "2026-07-08T18:40:00Z"}
    ],
    "max_languages": 5
  }
}

Search synonym limits

GET read_search

Get search synonym limits.

Returns validation and list controls. list_page_size is the default page size; list_max_limit is the maximum accepted size. page_size_options suggests UI choices, but any integer from 1 to list_max_limit is accepted. max_terms_per_group limits terms in one group, not the number of groups in a store. max_term_length and search_max_length count Unicode code points. sort_columns lists the accepted sort keys. All fields shown in the response are present.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
The Authorization header is missing.
401 INVALID_TOKEN
The Bearer header or token prefix is malformed.
401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED
The token was not accepted: it is unknown, expired, revoked, or replaced, or its app was uninstalled. Returned for app, App Bridge session, and Store Admin tokens alike.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 API_VERSION_UNSUPPORTED
The credential is pinned to an API version that cannot be served.
429 RATE_LIMITED
The request allowance is exhausted. Wait for Retry-After before retrying.
403 STORE_API_SCOPE_REQUIRED
The token does not grant the required resource scope. A write_search grant also permits reads.

curl 'https://api-store.tringify.com/api/2025-01/search-synonyms/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/search-synonyms/limits", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/search-synonyms/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"list_page_size":25,"list_max_limit":100,"page_size_options":[10,25,50,100],"search_max_length":100,"max_terms_per_group":25,"max_term_length":64,"sort_columns":["created_at","updated_at","locale"]}}

List search synonyms

GET read_search

List the store's search synonym groups.

Omit locale to list groups across the store's languages. A supplied locale must be enabled on the store. data.groups is an array of complete group objects; data.total is the number of groups matching the filters before pagination. An empty result or a page beyond the end returns groups: [] and the matching total. The default order is created_at descending; ties use ID descending. See the group response fields above.

Query parameters

Name	Type	Description
`page`	`integer`	Positive page number. Missing or empty uses the default; zero, negative and non-integer values are rejected. Default: `1` Example: `1`
`per_page`	`integer`	Any integer from 1 to 100. Missing or empty uses the default. Default: `25` Example: `25`
`search`	`string`	Case-insensitive substring of a term or locale code; at most 100 Unicode code points. Percent and underscore are treated literally. Example: `tee`
`locale`	`string`	Enabled store language code, matched without case sensitivity. Omit or leave empty for all languages. The wildcard * is not supported. Example: `en`
`sort_by`	`string`	created_at, updated_at, or locale; other values are rejected. Default: `created_at` Example: `updated_at`
`sort_direction`	`string`	Lowercase asc or desc; other values are rejected. Default: `desc` Example: `desc`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
The Authorization header is missing.
401 INVALID_TOKEN
The Bearer header or token prefix is malformed.
401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED
The token was not accepted: it is unknown, expired, revoked, or replaced, or its app was uninstalled. Returned for app, App Bridge session, and Store Admin tokens alike.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 API_VERSION_UNSUPPORTED
The credential is pinned to an API version that cannot be served.
429 RATE_LIMITED
The request allowance is exhausted. Wait for Retry-After before retrying.
403 STORE_API_SCOPE_REQUIRED
The token does not grant the required resource scope. A write_search grant also permits reads.
400 INVALID_INPUT
A query value or JSON body has an invalid type or format.
400 SEARCH_SYNONYM_LOCALE_INVALID
The language code is unsupported or is not enabled on the store.

curl 'https://api-store.tringify.com/api/2025-01/search-synonyms?locale=en&page=1&per_page=25&search=tee&sort_by=updated_at&sort_direction=desc' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/search-synonyms?locale=en&page=1&per_page=25&search=tee&sort_by=updated_at&sort_direction=desc", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/search-synonyms?locale=en&page=1&per_page=25&search=tee&sort_by=updated_at&sort_direction=desc",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"groups":[{"id":"3e41dbac-a931-4c43-9ff0-d430fa7b79c1","store_id":"786b2499-ee1c-4c00-8e71-3512f4676369","locale":"en","terms":["tee","t-shirt"],"created_at":"2026-08-03T14:30:00Z","updated_at":"2026-08-03T14:30:00Z"}],"total":1}}

Create search synonyms

POST write_search

Create a search synonym group.

Send JSON with an enabled language code and 2–25 terms. Leading and trailing whitespace is removed, repeated spaces become one, and Unicode text is normalized. Saved case and order are preserved. Each trimmed term can contain at most 64 Unicode code points. Empty terms and case-insensitive duplicates are rejected. A trimmed term cannot already belong to another group in the same store and language; that conflict returns 409. The same term can be used in another language. Success returns the complete group plus code: SEARCH_SYNONYM_CREATED and an English message, and emits search_synonyms/create.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`locale` required	`string`	Enabled store language code, matched without case sensitivity. Surrounding whitespace is trimmed; * is not supported. Example: `en`
`terms` required	`array<string>`	Complete group of 2–25 distinct, nonempty words or phrases; at most 64 Unicode code points per trimmed term. Example: `["tee","t-shirt"]`

Errors

401 UNAUTHORIZED
The Authorization header is missing.
401 INVALID_TOKEN
The Bearer header or token prefix is malformed.
401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED
The token was not accepted: it is unknown, expired, revoked, or replaced, or its app was uninstalled. Returned for app, App Bridge session, and Store Admin tokens alike.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 API_VERSION_UNSUPPORTED
The credential is pinned to an API version that cannot be served.
429 RATE_LIMITED
The request allowance is exhausted. Wait for Retry-After before retrying.
403 STORE_API_SCOPE_REQUIRED
The token does not grant the required resource scope. A write_search grant also permits reads.
400 INVALID_INPUT
A query value or JSON body has an invalid type or format.
400 SEARCH_SYNONYM_LOCALE_INVALID
The language code is unsupported or is not enabled on the store.
400 SEARCH_SYNONYM_LOCALE_REQUIRED
The required or supplied locale is blank.
400 SEARCH_SYNONYM_TERMS_REQUIRED
The required or supplied term array is empty.
400 SEARCH_SYNONYM_TERMS_MIN
The term array contains fewer than two terms.
400 SEARCH_SYNONYM_TERMS_MAX
The term array contains more than 25 terms; params.max gives the limit.
400 SEARCH_SYNONYM_TERM_EMPTY
A term is blank after Unicode normalization and whitespace normalization.
400 SEARCH_SYNONYM_TERM_TOO_LONG
A trimmed term exceeds 64 Unicode code points; params.max gives the limit.
400 SEARCH_SYNONYM_TERM_DUPLICATE
Two terms in the request match case-insensitively after Unicode normalization and whitespace normalization; params.term identifies the duplicate.
409 SEARCH_SYNONYM_TERM_IN_USE
A term belongs to another group in this store and language; params.term identifies a conflicting term.

curl -X POST 'https://api-store.tringify.com/api/2025-01/search-synonyms' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "locale": "en",
  "terms": [
    "tee",
    "t-shirt"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/search-synonyms", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "locale": "en",
    "terms": [
      "tee",
      "t-shirt"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/search-synonyms",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "locale": "en",
        "terms": ["tee", "t-shirt"],
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"id":"3e41dbac-a931-4c43-9ff0-d430fa7b79c1","store_id":"786b2499-ee1c-4c00-8e71-3512f4676369","locale":"en","terms":["tee","t-shirt"],"created_at":"2026-08-03T14:30:00Z","updated_at":"2026-08-03T14:30:00Z"},"code":"SEARCH_SYNONYM_CREATED","message":"Synonym group created."}

Update search synonyms

PUT write_search

Update a search synonym group.

This PUT merges the supplied fields. Omitted or null fields retain their current values. A supplied terms array replaces the whole group; it does not append. The create validation rules still apply, so an empty array cannot clear a group. Changing locale moves the group to that enabled language and checks term ownership there. Even {} is accepted: it preserves the locale and terms, refreshes updated_at, and emits search_synonyms/update. The response contains the complete saved group with code: SEARCH_SYNONYM_UPDATED and an English message. A well-formed ID absent from the token's store returns 404.

Path parameters

Name	Type	Description
`synonymId` required	`string`	The group's UUID, returned by list or create. Use an ID from the token's store. Example: `3e41dbac-a931-4c43-9ff0-d430fa7b79c1`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`locale`	`string`	New enabled store language code. Omit or use null to retain the current language. Example: `en`
`terms`	`array<string>`	Complete replacement group, using the create limits. Omit or use null to retain the current terms. Example: `["tee","t-shirt"]`

Errors

401 UNAUTHORIZED
The Authorization header is missing.
401 INVALID_TOKEN
The Bearer header or token prefix is malformed.
401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED
The token was not accepted: it is unknown, expired, revoked, or replaced, or its app was uninstalled. Returned for app, App Bridge session, and Store Admin tokens alike.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 API_VERSION_UNSUPPORTED
The credential is pinned to an API version that cannot be served.
429 RATE_LIMITED
The request allowance is exhausted. Wait for Retry-After before retrying.
403 STORE_API_SCOPE_REQUIRED
The token does not grant the required resource scope. A write_search grant also permits reads.
400 INVALID_INPUT
A query value or JSON body has an invalid type or format.
400 SEARCH_SYNONYM_LOCALE_INVALID
The language code is unsupported or is not enabled on the store.
400 SEARCH_SYNONYM_LOCALE_REQUIRED
The required or supplied locale is blank.
400 SEARCH_SYNONYM_TERMS_REQUIRED
The required or supplied term array is empty.
400 SEARCH_SYNONYM_TERMS_MIN
The term array contains fewer than two terms.
400 SEARCH_SYNONYM_TERMS_MAX
The term array contains more than 25 terms; params.max gives the limit.
400 SEARCH_SYNONYM_TERM_EMPTY
A term is blank after Unicode normalization and whitespace normalization.
400 SEARCH_SYNONYM_TERM_TOO_LONG
A trimmed term exceeds 64 Unicode code points; params.max gives the limit.
400 SEARCH_SYNONYM_TERM_DUPLICATE
Two terms in the request match case-insensitively after Unicode normalization and whitespace normalization; params.term identifies the duplicate.
409 SEARCH_SYNONYM_TERM_IN_USE
A term belongs to another group in this store and language; params.term identifies a conflicting term.
404 SEARCH_SYNONYM_NOT_FOUND
The well-formed group ID does not exist in the token's store.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/search-synonyms/3e41dbac-a931-4c43-9ff0-d430fa7b79c1' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "locale": "en",
  "terms": [
    "tee",
    "t-shirt"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/search-synonyms/3e41dbac-a931-4c43-9ff0-d430fa7b79c1", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "locale": "en",
    "terms": [
      "tee",
      "t-shirt"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/search-synonyms/3e41dbac-a931-4c43-9ff0-d430fa7b79c1",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "locale": "en",
        "terms": ["tee", "t-shirt"],
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"id":"3e41dbac-a931-4c43-9ff0-d430fa7b79c1","store_id":"786b2499-ee1c-4c00-8e71-3512f4676369","locale":"en","terms":["tee","t-shirt"],"created_at":"2026-08-03T14:30:00Z","updated_at":"2026-08-03T14:35:00Z"},"code":"SEARCH_SYNONYM_UPDATED","message":"Synonym group updated."}

Delete search synonyms

DELETE write_search

Delete a search synonym group.

Removes the group from the token's store and emits search_synonyms/delete. Success has a code and message, with no data object. Repeating the deletion of a well-formed ID returns 404 once the group is absent; there is no restore endpoint.

Path parameters

Name	Type	Description
`synonymId` required	`string`	The group's UUID, returned by list or create. Use an ID from the token's store. Example: `3e41dbac-a931-4c43-9ff0-d430fa7b79c1`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
The Authorization header is missing.
401 INVALID_TOKEN
The Bearer header or token prefix is malformed.
401 STORE_ADMIN_TOKEN_RUNTIME_UNAUTHORIZED
The token was not accepted: it is unknown, expired, revoked, or replaced, or its app was uninstalled. Returned for app, App Bridge session, and Store Admin tokens alike.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 API_VERSION_UNSUPPORTED
The credential is pinned to an API version that cannot be served.
429 RATE_LIMITED
The request allowance is exhausted. Wait for Retry-After before retrying.
403 STORE_API_SCOPE_REQUIRED
The token does not grant the required resource scope. A write_search grant also permits reads.
404 SEARCH_SYNONYM_NOT_FOUND
The well-formed group ID does not exist in the token's store.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/search-synonyms/3e41dbac-a931-4c43-9ff0-d430fa7b79c1' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/search-synonyms/3e41dbac-a931-4c43-9ff0-d430fa7b79c1", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/search-synonyms/3e41dbac-a931-4c43-9ff0-d430fa7b79c1",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"code":"SEARCH_SYNONYM_DELETED","message":"Synonym group deleted."}