Customiser languages

Create a customiser language

Copy page

Add a language to the customiser.

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

Create a customiser language

Add a language to the customiser. The language starts as a draft with one blank translation row per catalogue key: nothing a shopper sees changes until you write its required copy and publish it. `language_code` is an IETF language tag and is normalised to its canonical form, so `fr_ca` and `FR-ca` both create `fr-CA`. `source_language_code` names the language this one is translated from and defaults to the customiser default language; `display_name` defaults to the tag own language name. A create is refused with a 422 `validation_failed` when the tag is malformed, when the customiser already has that language, or when `source_language_code` names a language it does not have. The new language is never the default: making it the default is a separate operation that requires it to be published and complete first. The create clears the customiser cached storefront configuration and runs the advisory language sync, which is what seeds the translation rows. It never regenerates your Shopify products, product images, or product cache. An `Idempotency-Key` header (1-255 visible ASCII characters, e.g. a UUID) is required: repeating the same key with the same body replays the original response (marked `Idempotency-Replay: true`) without creating a second language, and the same key with a different body is a 409 problem with code `idempotency_key_conflict`. Requires the `customisers:write` scope. A 400 problem means the body is not valid JSON, or the `Idempotency-Key` header is missing or malformed. A 422 problem with code `unknown_field` means the body names properties this operation does not define. 401, 403, 404, and 429 problems behave as on the list operation, with `customisers:write` as the required scope.

Create a customiser language

Overview

The language starts as a draft with one blank translation row per catalogue key: nothing a shopper sees changes until you write its required copy and publish it. language_code is an IETF language tag and is normalised to its canonical form, so fr_ca and FR-ca both create fr-CA. source_language_code names the language this one is translated from and defaults to the customiser default language; display_name defaults to the tag own language name. A create is refused with a 422 validation_failed when the tag is malformed, when the customiser already has that language, or when source_language_code names a language it does not have. The new language is never the default: making it the default is a separate operation that requires it to be published and complete first. The create clears the customiser cached storefront configuration and runs the advisory language sync, which is what seeds the translation rows. It never regenerates your Shopify products, product images, or product cache. An Idempotency-Key header (1-255 visible ASCII characters, e.g. a UUID) is required: repeating the same key with the same body replays the original response (marked Idempotency-Replay: true) without creating a second language, and the same key with a different body is a 409 problem with code idempotency_key_conflict. Requires the customisers:write scope. A 400 problem means the body is not valid JSON, or the Idempotency-Key header is missing or malformed. A 422 problem with code unknown_field means the body names properties this operation does not define. 401, 403, 404, and 429 problems behave as on the list 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

Request body

language_codestringbody

source_language_codestringbody

display_namestringbody

Request body example

{
  "language_code": "fr-CA",
  "source_language_code": "en",
  "display_name": "Canadian French"
}

Create a customiser language

curl https://web.signcustomiser.com/api/v3/customisers/1/languages \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "language_code": "fr-CA",
  "source_language_code": "en",
  "display_name": "Canadian French"
}'

{
  "data": {
    "object": "customiser_language",
    "customiser_id": 42,
    "language_code": "fr-CA",
    "source_language_code": "en",
    "display_name": "Canadian French",
    "status": "draft",
    "is_default": 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,
    "created_at": "2026-05-04T09:09:00Z",
    "updated_at": "2026-05-04T09:09:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/languages/fr-CA",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key",
  "title": "Missing idempotency key",
  "status": 400,
  "code": "missing_idempotency_key",
  "detail": "Provide an Idempotency-Key header for this write. Use a unique value for each logical request and reuse that value only when retrying the same request body.",
  "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/idempotency_key_conflict",
  "title": "Idempotency key conflict",
  "status": 409,
  "code": "idempotency_key_conflict",
  "detail": "This Idempotency-Key was already used for a different request body on this operation. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request payload failed validation. Correct the fields listed in errors and retry.",
  "errors": [
    {
      "pointer": "/language_code",
      "code": "invalid_value",
      "detail": "This customiser already has a language with that code."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}