Channel texts

Each sales channel can have its own title, description, handle and translatable attribute values, in every locale: the German text of your online store can differ from the German text of a marketplace. A field the channel does not set uses the product's own text in that locale. Read titles, descriptions and attributes in bulk with GET /products?channel=…; the handle in other locales only through these endpoints. The names of attribute options (a color, a material) a channel shows are in channel_labels of GET /attributes.

Base URL, authentication and conventions of this API are on the Catalog API page.

Endpoints

get/products/{product}/channels/{channel}/texts/{locale}Get a channel's texts in one locale
put/products/{product}/channels/{channel}/texts/{locale}Set a channel's texts in one locale

get/products/{product}/channels/{channel}/texts/{locale}

Get a channel's texts in one locale

The title, description, handle, translatable attribute values and SEO this channel shows in this locale. from_channel lists the fields the channel sets (an attribute as attributes.<code>, an SEO field as seo.<field>); the others are the product's own text in that locale (null, or no attribute, if there is none). In the default locale attributes is empty: there the values are the product's attributes. seo is there in every locale, the default one included.

GET https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/channels/{channel}/texts/{locale}

Authentication: Bearer token

Rate limit: 600 requests per 1m, per key (default; the catalog owner can set 1–6,000)

Path parameters

productstringrequired
Product id or SKU.

Example: TEE-001
channelstringrequired
A sales channel code (GET /channels).

Example: online-store
localestringrequired
A locale code of the catalog (GET /locales), the default one included.

Example: de

Responses

200The channel's texts in that locale.application/json
- dataChannelTextsrequired
  Child attributes
  channelstring
  localestring
  titlestring | null
  descriptionstring | null
  handlestring | null
  attributesobject
  Translatable attribute values with a value in this locale; a list as an array.
  
  seoobject
  Meta title, meta description and SEO handle this channel shows in this locale.
  
  Child attributes
  meta_titlestring | null
  meta_descriptionstring | null
  handlestring | null
  from_channelarray of string
  The fields this channel sets (title, description, handle, attributes.<code>, seo.<field>); the others are the product's text.
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_not_found, channel_not_found, locale_not_found, or not_found for a path that does not exist.application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject

Request

curl -X GET https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/channels/online-store/texts/de \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/channels/online-store/texts/de", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/channels/online-store/texts/de', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

Response

{
  "data": {
    "channel": "online-store",
    "locale": "de",
    "title": "Basic T-Shirt",
    "description": "<p>Bio-Baumwolle.</p>",
    "handle": null,
    "attributes": {
      "care": "Handwäsche"
    },
    "seo": {
      "meta_title": "Basic T-Shirt kaufen",
      "meta_description": null,
      "handle": null
    },
    "from_channel": [
      "title",
      "attributes.care",
      "seo.meta_title"
    ]
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "details": {}
  }
}

put/products/{product}/channels/{channel}/texts/{locale}

Set a channel's texts in one locale

Requires a read and write key.

Writes only the fields you send, for this channel and this locale: the product's own text and the other channels do not change. null (or an empty value for an attribute) removes the channel's text, so the field goes back to the product's text; a text of only spaces, or a description with no text left once cleaned, counts as empty. Recorded in the product's Activity with the channel and the locale.

A handle already used by another product (on the product or on this channel, in that locale) is a 400.

attributes takes translatable attributes only (text, rich text, link; a list as an array of strings), and only in a locale other than the default one: anything else is a 400 that names the attribute.

seo sets the channel's meta title, meta description and SEO handle in this locale, the default one included; null goes back to the product's SEO in that locale. A seo object without any of these three fields is a 400.

Writing does not publish anything to the channel.

PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/channels/{channel}/texts/{locale}

Authentication: Bearer token

Rate limit: 600 requests per 1m, per key (default; the catalog owner can set 1–6,000)

Path parameters

productstringrequired
Product id or SKU.

Example: TEE-001
channelstringrequired
A sales channel code (GET /channels).

Example: online-store
localestringrequired
A locale code of the catalog (GET /locales), the default one included.

Example: de

Headers

Idempotency-Keystring
Any string of 1–255 printable ASCII characters, unique per change you mean (a UUID is fine). Sending the same request again with the same key within 48 hours returns the first answer without doing the work again (header Idempotent-Replayed: true). The same key with a different request is a 409 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_progress with Retry-After: 1. Answers 429 and 5xx are not stored: retry them with the same key.

max length 255
Example: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44

Request bodyapplication/json

titlestring | null
max length 255
descriptionstring | null
HTML.
handlestring | null
max length 255
attributesobject
Translated values by attribute code; null or empty goes back to the product's translation.
seoobject
The channel's SEO in this locale; null goes back to the product's SEO.
Child attributes
- meta_titlestring | null
  max length 255
- meta_descriptionstring | null
  max length 5000
- handlestring | null
  max length 255

Responses

200The channel's texts in that locale.application/json
- dataChannelTextsrequired
  Child attributes
  channelstring
  localestring
  titlestring | null
  descriptionstring | null
  handlestring | null
  attributesobject
  Translatable attribute values with a value in this locale; a list as an array.
  
  seoobject
  Meta title, meta description and SEO handle this channel shows in this locale.
  
  Child attributes
  meta_titlestring | null
  meta_descriptionstring | null
  handlestring | null
  from_channelarray of string
  The fields this channel sets (title, description, handle, attributes.<code>, seo.<field>); the others are the product's text.
400The request must change: validation_failed (see details, one list of messages per field), invalid_json, invalid_cursor, product_not_written, variant_not_written, not_written, image_not_downloadable. application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject
403read_only_key: this key cannot write.application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_not_found, channel_not_found, locale_not_found, or not_found for a path that does not exist.application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject
409idempotency_key_reused, idempotency_key_in_progress, webhook_limit. application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject

Request

curl -X PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/channels/online-store/texts/de \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Basic T-Shirt",
  "description": "<p>Bio-Baumwolle.</p>",
  "attributes": {
    "care": "Handwäsche"
  },
  "seo": {
    "meta_title": "Basic T-Shirt kaufen"
  }
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/channels/online-store/texts/de", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Basic T-Shirt",
    "description": "<p>Bio-Baumwolle.</p>",
    "attributes": {
      "care": "Handwäsche"
    },
    "seo": {
      "meta_title": "Basic T-Shirt kaufen"
    }
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/channels/online-store/texts/de', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'title' => 'Basic T-Shirt',
        'description' => '<p>Bio-Baumwolle.</p>',
        'attributes' => [
            'care' => 'Handwäsche',
        ],
        'seo' => [
            'meta_title' => 'Basic T-Shirt kaufen',
        ],
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

Response

{
  "data": {
    "channel": "online-store",
    "locale": "de",
    "title": "Basic T-Shirt",
    "description": "<p>Bio-Baumwolle.</p>",
    "handle": null,
    "attributes": {
      "care": "Handwäsche"
    },
    "seo": {
      "meta_title": "Basic T-Shirt kaufen",
      "meta_description": null,
      "handle": null
    },
    "from_channel": [
      "title",
      "attributes.care",
      "seo.meta_title"
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid: see details.",
    "request_id": "7c0f8a1e-3b2d-4e5f-9a6b-1c2d3e4f5a6b",
    "details": {
      "variants.0.prices.0.price_list": [
        "Unknown price list \"usa\". GET /price-lists lists them."
      ]
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "request_id": "string",
    "details": {}
  }
}

Was this page helpful?