Customisers

get_customiser_language

read

Get customiser language

Copy page

Read one language record, and read a bounded slice of its translation entries when the strings themselves are needed.

Overview

Reads one language a customiser publishes, addressed by its BCP 47 language code, and with include translations a filtered page of its translation entries as well. A language has no integer id: the language code is the identifier the public API uses. The translation page is bounded and filterable, because a customiser full dictionary is too large to return at once. It requires the customisers:read scope and has no side effects.

Permission

Requires thecustomisers:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers and a language code from list_customiser_languages.
A merchant has connected this store and approved the customisers:read scope.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

language_codestringrequired

The BCP 47 language tag the language is addressed by, such as fr or pt-BR, from list_customiser_languages.

includearray of string

Add translations to return one filtered page of translation entries alongside the language record.

translation_filterobject

Filters applied to the translation page. Ignored unless include contains translations. An unknown filter is rejected, never ignored.

translation_filter.groupstring

Only entries in this translation group.

translation_filter.keystring

Only entries whose key matches this value.

translation_filter.requiredstring

Only entries that are, or are not, required.

One of: true, false

translation_filter.retiredstring

Only entries that are, or are not, retired.

One of: true, false

limitinteger

How many translation entries to return, between 1 and 100. Defaults to 20. Ignored unless include contains translations.

cursorstring

The opaque next_cursor value from the previous translation page, sent back with identical filters.

Result

One language record. With include translations, one page of translation entries and its own pagination block, never the whole dictionary.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

languageobjectalways present

The language record.

language.language_codestringalways present

language.source_language_codestring or null

language.display_namestring or null

language.statusstringalways present

language.is_defaultbooleanalways present

language.translation_summaryobject or null

language.ai_translationobject or null

language.published_atstring or null

language.updated_atstring or null

translationsobject

One page of translation entries, present only when include contained translations.

translations.entriesarray of objectalways present

translations.paginationobjectalways present

translations.pagination.has_morebooleanalways present

translations.pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without customisers:read.

invalid_parameter

A translation filter is not one this API accepts; the accepted set is group, key, required and retired.

resource_not_found

No customiser with that id, or no language with that code on it. Call list_customiser_languages to rediscover a valid code.

Read a language with its untranslated required keys

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr",
      "include": [
        "translations"
      ],
      "translation_filter": {
        "required": "true"
      },
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "language": {
        "language_code": "fr",
        "source_language_code": "en",
        "display_name": "French",
        "status": "draft",
        "is_default": false,
        "translation_summary": {
          "key_count": 184,
          "required_key_count": 96,
          "translated_key_count": 12,
          "missing_required_key_count": 84,
          "publishable": false
        },
        "ai_translation": null,
        "published_at": null,
        "updated_at": "2026-05-04T09:11:20Z"
      },
      "translations": {
        "entries": [
          {
            "key": "selection:12:label",
            "group": "selections",
            "required": true,
            "source_text": "Colour",
            "draft_value": "Couleur",
            "published_value": null
          }
        ],
        "pagination": {
          "has_more": true,
          "next_cursor": "eyJrZXkiOiJzIn0"
        }
      }
    }
  }
}

A language code the customiser does not publish (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "zz"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "resource_not_found",
        "title": "Resource not found",
        "detail": "The requested resource does not exist or does not belong to the authenticated store.",
        "recovery": "The identifier does not exist in this store. Use the matching list tool to rediscover a valid id."
      }
    }
  }
}