/

Contents

CatalogCatalog API · v1

Product parts

Attributes, one translation, categories and images of a product.

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

Endpoints

put/products/{product}/attributesSet attribute values
put/products/{product}/translations/{locale}Set one translation
put/products/{product}/categoriesSet the categories
post/products/{product}/imagesAdd an image
patch/products/{product}/images/{image}Change alt text or position
DEL/products/{product}/images/{image}Delete an image

put/products/{product}/attributes

Set attribute values

Requires a read and write key.

The values sent, by attribute code (GET /attributes); other attributes keep their value. For an attribute with options, send the option code or its label: a value the attribute does not have yet becomes a new option.

PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/attributes

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

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

attributesobjectrequired
attribute_setstring
Name or id of the attribute set to assign.

Responses

200The product as it is now, and what happened.application/json
- dataProductrequired
  Child attributes
  idinteger
  skustring
  external_idstring | null
  The id this key gave the product.
  
  titlestring | null
  descriptionstring | null
  handlestring | null
  statusstring | null
  product_typestring | null
  brandstring | null
  attribute_setstring | null
  model_codestring | null
  genderstring | null
  seasonstring | null
  colorstring | null
  materialstring | null
  made_instring | null
  compositionstring | null
  categoriesarray of ProductCategory
  Attributes of each item
  idinteger
  namestring
  pathstring
  Example: Clothing > Tops
  attributesobject
  Values by attribute code. Options as their code; several options as their codes, comma separated.
  
  translationsobject
  Locales other than the default one.
  
  imagesarray of Image
  Attributes of each item
  idinteger
  urlstring
  altstring | null
  positioninteger
  widthinteger | null
  heightinteger | null
  variantsarray of Variant
  Attributes of each item
  idinteger
  skustring
  barcodestring | null
  optionsobject
  The options that tell variants apart: attribute code → option code ({"size": "m"}). Option codes are normalised, so a size sent as M comes back as m.
  
  coststring | null
  weightnumber | null
  weight_unitstring | null
  pricesarray of object
  Attributes of each item
  price_liststring
  currencystring | null
  pricestring | null
  Example: 19.90
  sale_pricestring | null
  stockarray of object
  Attributes of each item
  locationstring
  availableinteger
  on_handinteger
  updated_atstring (date-time) | null
  When the product last changed; null if it has not changed since this field exists.
- resultWriteResultrequired
  Child attributes
  statusstringrequired
  partial: some variants could not be written (see errors), the rest was. skipped: the key's field rule left nothing to write.
  
  One ofcreatedupdatedpartialskipped
  errorsarray of objectrequired
  Attributes of each item
  variant_skustring | null
  messagestring
  notesarray of stringrequired
  Fields not written and why (field rule, field owned by another system).
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
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_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 PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/attributes \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "attributes": {
    "color": "red",
    "fit": "regular"
  }
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/attributes", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "attributes": {
      "color": "red",
      "fit": "regular"
    }
  }),
});
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/attributes', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'attributes' => [
            'color' => 'red',
            'fit' => 'regular',
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "id": 1,
    "sku": "string",
    "external_id": "string",
    "title": "string",
    "description": "string",
    "handle": "string",
    "status": "string",
    "product_type": "string",
    "brand": "string",
    "attribute_set": "string",
    "model_code": "string",
    "gender": "string",
    "season": "string",
    "color": "string",
    "material": "string",
    "made_in": "string",
    "composition": "string",
    "categories": [
      {
        "id": 1,
        "name": "string",
        "path": "Clothing > Tops"
      }
    ],
    "attributes": {},
    "translations": {},
    "images": [
      {
        "id": 1,
        "url": "string",
        "alt": "string",
        "position": 1,
        "width": 1,
        "height": 1
      }
    ],
    "variants": [
      {
        "id": 1,
        "sku": "string",
        "barcode": "string",
        "options": {},
        "cost": "string",
        "weight": 1.5,
        "weight_unit": "string",
        "prices": [
          {
            "price_list": "string",
            "currency": "string",
            "price": "19.90",
            "sale_price": "string"
          }
        ],
        "stock": [
          {
            "location": "string",
            "available": 1,
            "on_hand": 1
          }
        ]
      }
    ],
    "updated_at": "2026-10-01T09:30:00Z"
  },
  "result": {
    "status": "created",
    "errors": [
      {
        "variant_sku": "string",
        "message": "string"
      }
    ],
    "notes": [
      "string"
    ]
  }
}

{
  "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": {}
  }
}

put/products/{product}/translations/{locale}

Set one translation

Requires a read and write key.

PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/translations/{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
localestringrequired
A locale code of the catalog (GET /locales). The default locale writes the product's own title and description.

Example: it

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
max length 255
descriptionstring
HTML, up to 65,000 characters.

Responses

200The product as it is now, and what happened.application/json
- dataProductrequired
  Child attributes
  idinteger
  skustring
  external_idstring | null
  The id this key gave the product.
  
  titlestring | null
  descriptionstring | null
  handlestring | null
  statusstring | null
  product_typestring | null
  brandstring | null
  attribute_setstring | null
  model_codestring | null
  genderstring | null
  seasonstring | null
  colorstring | null
  materialstring | null
  made_instring | null
  compositionstring | null
  categoriesarray of ProductCategory
  Attributes of each item
  idinteger
  namestring
  pathstring
  Example: Clothing > Tops
  attributesobject
  Values by attribute code. Options as their code; several options as their codes, comma separated.
  
  translationsobject
  Locales other than the default one.
  
  imagesarray of Image
  Attributes of each item
  idinteger
  urlstring
  altstring | null
  positioninteger
  widthinteger | null
  heightinteger | null
  variantsarray of Variant
  Attributes of each item
  idinteger
  skustring
  barcodestring | null
  optionsobject
  The options that tell variants apart: attribute code → option code ({"size": "m"}). Option codes are normalised, so a size sent as M comes back as m.
  
  coststring | null
  weightnumber | null
  weight_unitstring | null
  pricesarray of object
  Attributes of each item
  price_liststring
  currencystring | null
  pricestring | null
  Example: 19.90
  sale_pricestring | null
  stockarray of object
  Attributes of each item
  locationstring
  availableinteger
  on_handinteger
  updated_atstring (date-time) | null
  When the product last changed; null if it has not changed since this field exists.
- resultWriteResultrequired
  Child attributes
  statusstringrequired
  partial: some variants could not be written (see errors), the rest was. skipped: the key's field rule left nothing to write.
  
  One ofcreatedupdatedpartialskipped
  errorsarray of objectrequired
  Attributes of each item
  variant_skustring | null
  messagestring
  notesarray of stringrequired
  Fields not written and why (field rule, field owned by another system).
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
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_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 PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/translations/it \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Maglietta basic",
  "description": "<p>Cotone biologico.</p>"
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/translations/it", {
  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": "Maglietta basic",
    "description": "<p>Cotone biologico.</p>"
  }),
});
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/translations/it', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'title' => 'Maglietta basic',
        'description' => '<p>Cotone biologico.</p>',
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "id": 1,
    "sku": "string",
    "external_id": "string",
    "title": "string",
    "description": "string",
    "handle": "string",
    "status": "string",
    "product_type": "string",
    "brand": "string",
    "attribute_set": "string",
    "model_code": "string",
    "gender": "string",
    "season": "string",
    "color": "string",
    "material": "string",
    "made_in": "string",
    "composition": "string",
    "categories": [
      {
        "id": 1,
        "name": "string",
        "path": "Clothing > Tops"
      }
    ],
    "attributes": {},
    "translations": {},
    "images": [
      {
        "id": 1,
        "url": "string",
        "alt": "string",
        "position": 1,
        "width": 1,
        "height": 1
      }
    ],
    "variants": [
      {
        "id": 1,
        "sku": "string",
        "barcode": "string",
        "options": {},
        "cost": "string",
        "weight": 1.5,
        "weight_unit": "string",
        "prices": [
          {
            "price_list": "string",
            "currency": "string",
            "price": "19.90",
            "sale_price": "string"
          }
        ],
        "stock": [
          {
            "location": "string",
            "available": 1,
            "on_hand": 1
          }
        ]
      }
    ],
    "updated_at": "2026-10-01T09:30:00Z"
  },
  "result": {
    "status": "created",
    "errors": [
      {
        "variant_sku": "string",
        "message": "string"
      }
    ],
    "notes": [
      "string"
    ]
  }
}

{
  "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": {}
  }
}

put/products/{product}/categories

Set the categories

Requires a read and write key.

The full set of categories of the product, by id (GET /categories): categories not in the list are removed, and an empty list removes them all. With the field rule inserimento only a product without categories can be changed; with nucleo, none.

PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/categories

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

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

category_idsarray of integerrequired
max items 200

Responses

200The categories of the product now.application/json
- dataarray of ProductCategoryrequired
  Attributes of each item
  idinteger
  namestring
  pathstring
  Example: Clothing > Tops
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
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_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
409field_rule (the key's field rule does not allow this change), field_locked (the change touches fields another connected system owns; details.locked lists them), idempotency_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/categories \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "category_ids": [
    12,
    31
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/categories", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "category_ids": [
      12,
      31
    ]
  }),
});
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/categories', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'category_ids' => [
            12,
            31,
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": [
    {
      "id": 1,
      "name": "string",
      "path": "Clothing > Tops"
    }
  ]
}

{
  "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": {}
  }
}

post/products/{product}/images

Add an image

Requires a read and write key.

Either JSON with the url of the image, or multipart/form-data with the file in image.

From a URL, Nucleo downloads the image and stores it: no link to your server remains. Only public http(s) addresses; JPEG, PNG, WebP, GIF, AVIF, HEIC, TIFF or BMP up to 40 MB; never SVG. The same URL sent again for the same product returns the image already there (200).
As a file: JPEG, PNG or WebP up to 10 MB.

position starts at 1; without it the image goes last. With the field rule inserimento only a product without images can get one; with nucleo, none.

Image URLs sent in image_urls of a product are different: they are linked as they are, not downloaded.

POST https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/images

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

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, multipart/form-data

urlstring (uri)required
max length 2000
altstring
max length 255
positioninteger
min 1

Responses

200The image.application/json
- dataImagerequired
  Child attributes
  idinteger
  urlstring
  altstring | null
  positioninteger
  widthinteger | null
  heightinteger | null
201The image.application/json
- dataImagerequired
  Child attributes
  idinteger
  urlstring
  altstring | null
  positioninteger
  widthinteger | null
  heightinteger | null
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
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_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
409field_rule (the key's field rule does not allow this change), field_locked (the change touches fields another connected system owns; details.locked lists them), idempotency_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 POST https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://cdn.acme.example/tee-001-back.jpg",
  "alt": "Back view",
  "position": 2
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://cdn.acme.example/tee-001-back.jpg",
    "alt": "Back view",
    "position": 2
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'url' => 'https://cdn.acme.example/tee-001-back.jpg',
        'alt' => 'Back view',
        'position' => 2,
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "id": 1,
    "url": "string",
    "alt": "string",
    "position": 1,
    "width": 1,
    "height": 1
  }
}

{
  "data": {
    "id": 1,
    "url": "string",
    "alt": "string",
    "position": 1,
    "width": 1,
    "height": 1
  }
}

{
  "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": {}
  }
}

patch/products/{product}/images/{image}

Change alt text or position

Requires a read and write key.

PATCH https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/images/{image}

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
imageintegerrequired

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

altstring | null
max length 255
positioninteger
New position; the other images move.

min 1

Responses

200The image.application/json
- dataImagerequired
  Child attributes
  idinteger
  urlstring
  altstring | null
  positioninteger
  widthinteger | null
  heightinteger | null
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_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
409field_rule (the key's field rule does not allow this change), field_locked (the change touches fields another connected system owns; details.locked lists them), idempotency_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 PATCH 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images/{image}' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "alt": "string",
  "position": 1
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images/{image}", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "alt": "string",
    "position": 1
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images/{image}', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'alt' => 'string',
        'position' => 1,
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "id": 1,
    "url": "string",
    "alt": "string",
    "position": 1,
    "width": 1,
    "height": 1
  }
}

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

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

delete/products/{product}/images/{image}

Delete an image

Requires a read and write key.

DELETE https://api-catalog.nucleoplatform.com/api/catalog/v1/products/{product}/images/{image}

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
imageintegerrequired

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

Responses

204Deleted.
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_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
409field_rule (the key's field rule does not allow this change), field_locked (the change touches fields another connected system owns; details.locked lists them), idempotency_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 DELETE 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images/{image}' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images/{image}", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/images/{image}', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'http_errors' => false,
]);

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

Response

HTTP 204 — Deleted.

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

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

Was this page helpful?