Customisers

create_customiser_language

write

Create customiser language

Copy page

Start a new storefront language for a customiser, which the merchant then translates and publishes.

Overview

Adds a language to a customiser as a draft with one blank translation row per catalogue key. Nothing a shopper sees changes until the required copy is written with update_customiser_language_translations and the language is published with publish_customiser_language. The language code is normalised to its canonical BCP 47 form, and the customiser must not already have it. The new language is never the default. It does not start an AI translation. It requires the customisers:write scope and an idempotency_key; dry_run true checks the create without adding anything.

Permission

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

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
A language code the customiser does not have yet; list_customiser_languages shows the ones it has.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Adds one draft language with a blank translation row per catalogue key. Shopper-visible copy does not change.
Clears the customiser cached storefront configuration and runs the language sync.
Claims the idempotency_key for at least 24 hours.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

language_codestringrequired

The IETF language tag to add, such as fr or fr-CA. It is normalised to its canonical form, so fr_ca creates fr-CA. The customiser must not already have it.

source_language_codestring

The language this one is translated from. It must be a language the customiser already has. Defaults to the authoring language, or to the default language when no authoring language is recorded.

display_namestring

How the language is named in the merchant admin. Defaults to the name of the language in that language.

idempotency_keystringrequired unless dry_run is true

A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict.

dry_runboolean

When true, the create is checked against the language tag rules and the languages the customiser already has is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. A dry run claims no key.

Result

The new language record with its translation summary. A dry run returns the create verdict instead and adds nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

languageobject

The created language. Absent on a dry run.

language.language_codestringalways present

language.source_language_codestring or null

language.display_namestring or null

language.statusstringalways present

language.is_defaultbooleanalways present

language.is_authoringbooleanalways present

language.translation_summaryobject or null

language.ai_translationobject or null

language.published_atstring or null

language.updated_atstring or null

dry_runboolean

Present and true only when dry_run was requested.

validboolean

Present only on a dry run, and always true: a failing dry run returns a tool error instead.

verdictobject

Present only on a dry run: the create verdict.

idempotent_replayboolean

True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.

Error cases

idempotency_key_conflict

The key was already used with other arguments. Re-send the original arguments or use a new key.

insufficient_scope

The connection was approved without customisers:write.

resource_not_found

No customiser with that id exists in this store.

validation_failed

The language code is not a valid IETF tag, the customiser already has it, or source_language_code names a language the customiser does not have. Read errors for the pointer.

Add Canadian French as a draft

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr-CA",
      "display_name": "Canadian French",
      "idempotency_key": "2f1c8a90-6b1e-4c3a-9d7f-8e0a1b2c3d4e"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "language": {
        "language_code": "fr-CA",
        "source_language_code": "en",
        "display_name": "Canadian French",
        "status": "draft",
        "is_default": false,
        "is_authoring": false,
        "translation_summary": {
          "key_count": 184,
          "required_key_count": 96,
          "translated_key_count": 0,
          "retired_key_count": 0,
          "missing_required_key_count": 96,
          "publishable": false
        },
        "ai_translation": null,
        "published_at": null,
        "updated_at": "2026-05-04T09:09:00Z"
      },
      "idempotent_replay": false
    }
  }
}

A language the customiser already has (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr",
      "idempotency_key": "3a2d9b01-7c2f-4d4b-8e80-9f1b2c3d4e5f"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The request payload failed validation. Correct the fields listed in errors and retry.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "errors": [
          {
            "pointer": "/language_code",
            "code": "invalid_value",
            "detail": "This customiser already has a language with that code."
          }
        ]
      }
    }
  }
}