Languages

Read and manage the store's publishing languages and default (source) language through the Store API.

Languages control which translated versions of store content can be published. Use the read_translations scope to read them and write_translations to make changes.

A store has one default language, where original content is written, plus the additional languages it publishes. The total number of enabled languages is limited by the store's plan. The default language must remain enabled. Before disabling a language, remove it from every storefront that uses it. Disabling a language permanently removes its stored translations, storefront messages, and localized search documents, and requires the same confirmation token flow as changing the default: the first request returns CONFIRMATION_REQUIRED; repeat with confirmed: true and that token. Adding languages does not require confirmation.

Changing the default language requires confirmation. The selected language becomes the new source language; Tringify does not translate existing source content as part of this change, and translations previously stored for the selected language are removed. The first request returns warnings and a short-lived confirmation token without making changes. Repeat the request with confirmed: true and that token to continue. If the selected language is not enabled, it is added when the store's language limit allows.

GET /languages is the enabled catalog a storefront can publish. Assigning those languages to a specific storefront is an Online Store Admin action, not part of this resource. Use /reference/languages to list every language Tringify supports before enabling one with PUT /languages.

Endpoints#

List languages

GET read_translations

List the store's enabled languages with the default flagged.

Returns every enabled language with its locale code, display label, native name, selector label, text direction, and default-language status. The response also includes the store's language limit, max_languages, which counts the default language and is never below 1. Once a downgrade is scheduled, it is the lower plan's limit. Locale codes use their canonical spelling, for example pt-BR. Content is authored in the default language and translated into the others. This list is the catalog a storefront can publish. Assigning those languages to a specific storefront is an Online Store Admin action and is not part of this resource.

Headers

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

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/languages", {
  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/languages",
    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
  }
}

Set languages

PUT write_translations

Update the store's enabled language set.

When locales is supplied, it is the complete set of locale codes the store should publish in. Repeated codes count once, and an identical set is a no-op that does not claim an update. Omitting locales leaves the enabled set unchanged. The default language must always be included in a supplied set — it cannot be removed here. Disabling a language permanently deletes its translations and requires confirmation: the first call that would remove locales returns CONFIRMATION_REQUIRED with warnings and a token bound to those locales; repeat with confirmed: true and that token. Adding languages does not require confirmation. Locale codes are matched without regard to letter case and stored in their canonical spelling, for example pt-BR. A language that is assigned to a storefront is protected (remove it from those storefronts first). The set size is capped by max_languages; once a downgrade is scheduled, the lower plan's limit applies. A store that already has more languages than its limit can still remove languages, but cannot add one until it is within the limit. Disabling a language cancels its active translation work and publishes store/locales/deleted for each removed language, in addition to store/locales/update.

Headers

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

Body parameters

Name	Type	Description
`locales`	`array<string>`	Complete enabled set of locale codes, including the default. Omit it to leave languages unchanged. Example: `["en", "hi", "fr"]`
`confirmed`	`boolean`	true on the second call, with the confirmation token, when locales are being disabled. Example: `true`
`confirmation_token`	`string`	Token from the first call's warning response when locales are being disabled. Example: `"ct_abc123"`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 STORE_LANGUAGE_REQUIRED
The locales list is empty.
400 STORE_LANGUAGE_INVALID
A locale code is not in the platform catalog.
400 STORE_LANGUAGE_LIMIT_EXCEEDED
The set adds a language beyond max_languages (the lower plan's limit once a downgrade is scheduled).
400 STORE_LANGUAGE_DEFAULT_REQUIRED
The default language is missing from the set.
409 STORE_LANGUAGE_IN_USE
A removed language is still assigned to one or more storefronts.
409 STORE_LOCALE_SERVED_BY_STOREFRONT
A storefront still serves the removed language; remove it from that storefront first.
409 STORE_LANGUAGE_REMOVAL_CONFLICT
Translations for a language being disabled changed during the request. Retry.
409 CONFIRMATION_REQUIRED
Disabling a language returns impact warnings and a confirmation token.
400 STORE_LANGUAGE_CONFIRMATION_INVALID
The confirmation token is invalid or expired.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/languages' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmation_token": "ct_abc123",
  "confirmed": true,
  "locales": [
    "en",
    "hi",
    "fr"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/languages", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "confirmation_token": "ct_abc123",
    "confirmed": true,
    "locales": [
      "en",
      "hi",
      "fr"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/languages",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "confirmation_token": "ct_abc123",
        "confirmed": True,
        "locales": ["en", "hi", "fr"],
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "code": "STORE_LANGUAGES_UPDATED",
  "message": "Languages updated.",
  "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
  }
}

Set default language

PUT write_translations

Change the store's default (source) language — a confirmed two-step.

The selected language becomes the source language for store content. This does not translate existing source content into the new language. Any translations stored for the selected language are permanently removed because that language will now contain source content. The first call returns impact warnings and a confirmation token without making changes; repeat the request with confirmed: true and that token to continue. Tokens are short-lived and single-use. A successful change publishes store/locales/update. store/translations/deleted is published only when translations, translated storefront messages, or active translation work were actually removed.

Headers

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

Body parameters

Name	Type	Description
`locale` required	`string`	Locale code to become the default, matched without regard to letter case. If it is not enabled yet, it is added when the plan limit allows. Example: `"hi"`
`confirmed`	`boolean`	true on the second call, with the confirmation token. Example: `true`
`confirmation_token`	`string`	Token from the first call's warning response. Example: `"ct_abc123"`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
409 CONFIRMATION_REQUIRED
The first call returns impact warnings and a confirmation token.
400 STORE_LANGUAGE_INVALID
The locale is not in the platform catalog.
400 STORE_LANGUAGE_DEFAULT_LIMIT_REACHED
The locale is not enabled and adding it would exceed max_languages (the lower plan's limit once a downgrade is scheduled).
400 STORE_LANGUAGE_CONFIRMATION_INVALID
The confirmation token is invalid or expired.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/languages/default' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmation_token": "ct_abc123",
  "confirmed": true,
  "locale": "hi"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/languages/default", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "confirmation_token": "ct_abc123",
    "confirmed": true,
    "locale": "hi"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/languages/default",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "confirmation_token": "ct_abc123",
        "confirmed": True,
        "locale": "hi",
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "code": "STORE_DEFAULT_LANGUAGE_CHANGED",
  "message": "Default language updated.",
  "data": {
    "default_locale": "hi"
  }
}

Remove language translations

DELETE write_translations

Delete all translation data for one enabled language without disabling it.

The first call returns warnings and a confirmation token without deleting anything. Repeat the request with confirmed: true and that token to permanently remove every stored content translation, translated storefront message, localized search document, pending AI suggestion, and translation CSV preview for the selected language. Active AI and CSV translation work is cancelled and cannot restore removed content. Completed import and export history remains available. The language remains enabled and its storefront assignments do not change. store/translations/deleted is published only when the reset removes data or cancels active work. The default language cannot be selected because it contains source content rather than translations.

Path parameters

Name	Type	Description
`locale` required	`string`	Enabled non-default locale whose translation data should be removed. Matched without regard to letter case; `pt-br` and `pt-BR` select the same language, and the webhook uses the canonical code. Example: `pt-BR`

Headers

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

Body parameters

Name	Type	Description
`confirmed`	`boolean`	true on the second call, with the confirmation token. Example: `true`
`confirmation_token`	`string`	Token returned by the first call. Example: `"ct_abc123"`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
409 CONFIRMATION_REQUIRED
The first call returns impact warnings and a confirmation token.
400 TRANSLATION_LOCALE_REQUIRED
The locale path parameter is empty.
400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN
The default language contains source content and cannot be reset as translation data.
400 TRANSLATION_LOCALE_NOT_ENABLED
The locale is not enabled for this store.
400 STORE_LANGUAGE_CONFIRMATION_INVALID
The confirmation token is invalid or expired.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/languages/pt-BR/translations' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmation_token": "ct_abc123",
  "confirmed": true
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/languages/pt-BR/translations", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "confirmation_token": "ct_abc123",
    "confirmed": true
  }),
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/languages/pt-BR/translations",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "confirmation_token": "ct_abc123",
        "confirmed": True,
    },
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "code": "STORE_TRANSLATIONS_DELETED",
  "message": "Translation data removed.",
  "data": null
}

Reference languages

GET

List every language available for storefront translation.

Returns each supported language's BCP 47 code, English name, native name, and right-to-left flag. Use it to build locale selectors and translation workflows.

Headers

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

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/reference/languages' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/reference/languages", {
  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/reference/languages",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "success": true,
  "data": {
    "languages": [
      {"code": "en", "name": "English", "native_name": "English", "rtl": false},
      {"code": "hi", "name": "Hindi", "native_name": "हिन्दी", "rtl": false}
    ]
  }
}

Webhook events#

Subscribe to language events when your app mirrors the enabled language set or stored translations. Updates contain the complete enabled set and default language. Removing a language and removing only its translation data are separate events. Requests that make no effective change do not publish an event.

Store languages updated

EVENT store/locales/update App scope: read_translations Staff permission: settings.languages:read

Fired when the store's enabled or default language changes. The payload carries the complete enabled set and default language.

Payload fields

Field	Type	Description
`locales`	`array`	Always present The complete enabled language set after the change, as BCP 47 locale codes.
`default_locale`	`string`	Always present The locale code of the store's default source language after the change.
`updated_at`	`string`	Always present When the language settings changed, in the store's time zone with its offset (RFC 3339).

Payload shape

Sample payload

{
  "default_locale": "en",
  "locales": [
    "en",
    "fr",
    "hi"
  ],
  "updated_at": "2026-07-08T18:40:00+05:30"
}

Store language removed

EVENT store/locales/deleted App scope: read_translations Staff permission: settings.languages:read

Fired when a language is removed from the store; its stored translations and localized storefront data are removed. Subscribers should discard their complete mirror for that language.

Payload fields

Field	Type	Description
`locale`	`string`	Always present The canonical locale code removed from the store's enabled language set, for example pt-BR.
`deleted_at`	`string`	Always present When the language and its stored localized data were removed, in the store's time zone with its offset (RFC 3339).

Payload shape

Sample payload

{
  "deleted_at": "2026-07-08T18:40:00+05:30",
  "locale": "fr"
}

Store translations deleted

EVENT store/translations/deleted App scope: read_translations Staff permission: settings.languages:read

Fired when stored translations, translated storefront messages, localized search documents, or active translation work for one enabled language are permanently removed without disabling the language. A reset that changes nothing does not fire this event.

Payload fields

Field	Type	Description
`locale`	`string`	Always present The canonical locale code of the enabled language whose stored translations were removed, for example pt-BR.
`deleted_at`	`string`	Always present When the stored translations became unavailable, in the store's time zone with its offset (RFC 3339).

Payload shape

Sample payload

{
  "deleted_at": "2026-07-08T18:40:00+05:30",
  "locale": "fr"
}