# POST 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.

- Source URL: https://www.signcustomiser.com/help/api/v3-post-create-a-customiser-language/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-post-create-a-customiser-language.md
- Group: Customiser languages
- Method: POST
- Path: /api/v3/customisers/{customiser_id}/languages
- Auth: Bearer token
- Required scopes: `customisers:write`

## Path parameters

- customiser_id (string, required): The customiser id, from the list customisers operation. Example: 1

## Body parameters

- language_code (string, optional): No description provided.
- source_language_code (string, optional): No description provided.
- display_name (string, optional): No description provided.

## Request body example

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

## cURL example

```bash
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"
}'
```

## Response examples

### 201 Language created

```json
{
  "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"
  }
}
```

### 400 Missing idempotency key

```json
{
  "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"
}
```

### 403 Insufficient scope

```json
{
  "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"
}
```

### 409 Idempotency key conflict

```json
{
  "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"
}
```

### 422 Duplicate language

```json
{
  "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"
}
```