Languages

Languages are store configuration that drives translations, so the scope pair is read_translations / write_translations.

A store publishes in an enabled set of languages, capped by its plan, with one default (source) language the catalog is authored in. Setting the language list always replaces the full set and must include the default; a language that still carries published translations can't be dropped until its translations are removed.

Changing the default is a confirmed two-step: the first call answers with the impact warnings (source-language change, translation re-basing, irreversibility) and a single-use confirmation token; re-send with confirmed: true and the token to apply. The platform's full language catalog is available at /reference/languages for building pickers — static, cached, token-only.

Endpoints#

List languages

GET read_translations

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

Returns the languages the store publishes in — code, name, native name — with the default (source) language flagged, plus the plan's language cap. Content is authored in the default language and translated into the others.

Headers

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

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
Token's per-window quota exceeded. Retry after the Retry-After header.

Response

200

Sample response

{
  "success": true,
  "data": {
    "locales": [
      {"code": "en", "name": "English", "native_name": "English", "is_default": true},
      {"code": "hi", "name": "Hindi", "native_name": "हिन्दी", "is_default": false}
    ],
    "default_locale": "en",
    "max_languages": 5
  }
}

Set languages

PUT write_translations

Replace the store's enabled language set.

Sends the full set of locale codes the store should publish in. The default language must always be included — it cannot be removed here. A language that is assigned to a storefront is protected (remove it from those storefronts first), and the set size is capped by the store's plan.

Headers

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

Body parameters

Name	Type	Description
`locales` required	`array<string>`	Full enabled set of locale codes, including the default. Example: `["en", "hi", "fr"]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
Token's per-window quota exceeded. Retry after the Retry-After header.
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 exceeds the plan's language cap.
400 STORE_LANGUAGE_DEFAULT_REQUIRED
The default language is missing from the set.
400 STORE_LANGUAGE_IN_USE
A removed language is still assigned to one or more storefronts.

Response

200

Sample response

{
  "success": true,
  "message": "Languages updated.",
  "data": {
    "locales": [
      {"code": "en", "name": "English", "native_name": "English", "is_default": true},
      {"code": "hi", "name": "Hindi", "native_name": "हिन्दी", "is_default": false}
    ]
  }
}

Set default language

PUT write_translations

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

The default language is the language your catalog is authored in, so changing it re-bases translations. The first call returns the impact warnings and a confirmation token instead of applying; re-send the same request with confirmed: true and the token to apply. Tokens are single-use and expire.

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. Must be in the enabled set. 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.
403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
Token's per-window quota exceeded. Retry after the Retry-After header.
400 STORE_LANGUAGE_INVALID
The locale is not in the platform catalog.
400 STORE_LANGUAGE_DEFAULT_REQUIRED
The locale is not in the store's enabled set.
400 STORE_LANGUAGE_CONFIRMATION_INVALID
The confirmation token is invalid or expired.
409 STORE_LANGUAGE_DEFAULT_WARNING_SOURCE
First-call warning response: carries the impact warnings and the confirmation token.

Response

200

Sample response

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

Reference languages

GET

Every language the platform supports.

The platform's full language catalog — code, English name, native name — for building an add-language picker. Static reference data, served cached; requires only a valid token, no specific scope.

Headers

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

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
Token's per-window quota exceeded. Retry after the Retry-After header.

Response

200

Sample response

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