Customiser languages

Set the default customiser language

Copy page

Make this language the customiser default. The storefront falls back to its copy when a shopper locale has no published language.

POST/api/v3/customisers/{customiser_id}/languages/{language_code}/default

Set the default customiser language

Make this language the customiser default. The storefront falls back to its copy when a shopper locale has no published language. Option, selection, setting, letter-part and form text keeps its authoring language, so this change does not change `is_authoring`. Exactly one language is the default, so the previous default loses it in the same transaction. A 422 problem with code `language_not_defaultable` means the language is not eligible: `reason` is `not_published` when it has never been published, or `incomplete_published_translations` when its published copy is missing a required key or has drifted from its source. Publish it first, then retry. Setting the default on the language that already holds it is accepted and changes nothing. The write clears the customiser cached storefront configuration and runs the advisory language sync. It never regenerates your Shopify products, product images, or product cache. An `Idempotency-Key` header is required. Requires the `customisers:write` scope. A 400 problem means the `Idempotency-Key` header is missing or malformed. 401, 403, 404, and 429 problems behave as on the read operation, with `customisers:write` as the required scope.

Set the default customiser language

Overview

Option, selection, setting, letter-part and form text keeps its authoring language, so this change does not change is_authoring. Exactly one language is the default, so the previous default loses it in the same transaction. A 422 problem with code language_not_defaultable means the language is not eligible: reason is not_published when it has never been published, or incomplete_published_translations when its published copy is missing a required key or has drifted from its source. Publish it first, then retry. Setting the default on the language that already holds it is accepted and changes nothing. The write clears the customiser cached storefront configuration and runs the advisory language sync. It never regenerates your Shopify products, product images, or product cache. An Idempotency-Key header is required. Requires the customisers:write scope. A 400 problem means the Idempotency-Key header is missing or malformed. 401, 403, 404, and 429 problems behave as on the read operation, with customisers:write as the required scope.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

language_codestringpathrequired

The language tag, from the list customiser languages operation.

Example: fr

Set the default customiser language

curl https://web.signcustomiser.com/api/v3/customisers/1/languages/fr/default \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

{
  "data": {
    "object": "customiser_language",
    "customiser_id": 42,
    "language_code": "fr",
    "source_language_code": "en",
    "display_name": "French",
    "status": "published",
    "is_default": true,
    "is_authoring": true,
    "translation_summary": {
      "key_count": 184,
      "required_key_count": 96,
      "translated_key_count": 184,
      "retired_key_count": 0,
      "missing_required_key_count": 0,
      "publishable": true
    },
    "ai_translation": null,
    "published_at": "2026-05-04T09:12:31Z",
    "created_at": "2026-05-04T09:09:00Z",
    "updated_at": "2026-05-04T09:14:02Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/languages/fr/default",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the customisers:write scope, but the API key grants the following scopes: customisers:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.",
  "required_scopes": [
    "customisers:write"
  ],
  "granted_scopes": [
    "customisers:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/language_not_defaultable",
  "title": "Language not eligible to be the default",
  "status": 422,
  "code": "language_not_defaultable",
  "detail": "The storefront uses the default language when another language has no published value for a key. Thus, the default language must be published. It must also have a current published value for each required key. Publish this language first, then retry.",
  "reason": "not_published",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}