Customiser languages

Set the default customiser language

Copy page

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

Set the default customiser language

Make this language the customiser default: the source every other language is translated from, and the copy the storefront falls back to when a shopper locale has no published language. Exactly one language carries it, so the previous default gives it up 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.

Overview

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 theAuthorization 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,
    "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 default language is the source every other language is translated from, so it must be published and carry a current published value for every required key. Publish this language first, then retry.",
  "reason": "not_published",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}