/

Contents

Products

Read, create, update and delete products. A product is addressed by its Nucleo id or by its sku (/products/123 or /products/TEE-001).

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

Endpoints

get/productsList products
post/productsCreate or update a product
get/products/{product}Get a product
patch/products/{product}Update a product
DEL/products/{product}Delete a product

get/products

List products

Products ordered by id, page by page. With updated_since, only the products that changed at or after that moment, ordered by when they changed: use the server_time of your previous sync (from GET /ping) or the latest updated_at you stored.

What counts as a change: anything recorded in the product's Activity in Nucleo (made in the app, by an import, by another connected system, by Atomo or by this API) and every change of a stock quantity made on the product page, by an import or by this API.

Deleted products. With updated_since, a product moved to Nucleo's trash comes back as {"id", "sku", "deleted": true, "updated_at"}: remove it from your copy. A product stays in the trash for 30 days (and can be restored, which counts as a change), then it is deleted for good and no longer listed. Without updated_since, products in the trash are not listed.

GET https://api-catalog.nucleoplatform.com/api/catalog/v1/products

Authentication: Bearer token

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

Query parameters

limitinteger
Items per page, 1–200.

min 1max 200default 50
Example: 50
cursorstring
The next_cursor of the previous page. A cursor works only with the same filters it was made with.
updated_sincestring (date-time)
ISO 8601 date-time. Only products changed at or after this moment, deleted ones included.

Example: 2026-10-13T08:00:00Z
skustring
Only these SKUs, comma separated (1–100).

Example: TEE-001,TEE-002
statusstring
Only products with this status code (for example active, draft).

Responses

200One page of products.application/json
- dataarray of Product | DeletedProductrequired
- next_cursorstring | nullrequired
  Pass it as cursor to get the next page; null on the last page.
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
401unauthorized: the key is missing, wrong or revoked.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
429rate_limited: wait the seconds in Retry-After.application/json
Headers
- Retry-After Seconds to wait.
- 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?limit=50&updated_since=2026-10-13T08%3A00%3A00Z&sku=TEE-001%2CTEE-002' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products?limit=50&updated_since=2026-10-13T08%3A00%3A00Z&sku=TEE-001%2CTEE-002", {
  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?limit=50&updated_since=2026-10-13T08%3A00%3A00Z&sku=TEE-001%2CTEE-002', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    '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": [],
          "stock": []
        }
      ],
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "next_cursor": "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": {}
  }
}

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

post/products

Create or update a product

Requires a read and write key.

Creates the product, or updates it if the SKU already exists (also if it is known by an earlier SKU). Without sku, an external_id this key already sent finds the product.

Only the fields you send are written; variants, prices and stock are added or updated, never removed (delete a variant with DELETE /products/{product}/variants/{variant}).

Answers 201 when the product was created and 200 when it existed. result.status says what happened; result.notes explains fields that were not written (the key's field rule, or a field owned by another system). A product that could not be written at all is a 400 product_not_written.

POST https://api-catalog.nucleoplatform.com/api/catalog/v1/products

Authentication: Bearer token

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

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

skustringrequired
max length 255pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$
external_idstring
Your id for the product. Remembered per key: later calls can send it instead of sku.

max length 255
titlestring
max length 255
descriptionstring
HTML; unsafe markup is removed.

max length 65000
statusstring
A status code of the catalog (for example active, draft). An unknown code is an error.
product_typestring
Created if new.

max length 255
brandstring
Created if new.

max length 255
categorystring
A category path (Clothing > Tops): added to the product's categories, created if new. To replace all categories use PUT /products/{product}/categories.

max length 500
model_codestring
max length 255
genderstring
max length 255
seasonstring
One or more season codes, comma separated (SS25, FW25).

max length 255
colorstring
max length 255
materialstring
max length 255
made_instring
ISO country code or country name.

max length 255
compositionstring
max length 2000
attribute_setstring
Name or id of the attribute set.
attributesobject
Values by attribute code (GET /attributes). An unknown code is an error.
translationsobject
By locale code (GET /locales). An unknown locale is an error.
image_urlsarray of string (uri)
Linked as they are (not downloaded); a URL already on the product is not added again. To store a copy in Nucleo, use POST /products/{product}/images.

max items 50
variantsarray of VariantInput
max items 500
Attributes of each item
- skustringrequired
  Unique in the whole catalog.
  
  max length 255pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$
- barcodestring
  Unique in the whole catalog.
  
  max length 255
- sizestring
  Size code; becomes the variant's size option (read back in options, as a normalised option code).
  
  max length 255
- costnumber
  min 0
- weightnumber
  min 0
- weight_unitstring
  One ofgkglboz
- pricesarray of PriceInput
  Attributes of each item
  - price_liststringrequired
    Price list code (GET /price-lists).
  - pricenumberrequired
    min 0
  - sale_pricenumber | null
    Discounted price on that list.
    
    min 0
- stockarray of StockInput
  Attributes of each item
  - locationstringrequired
    Location code (GET /locations).
  - availableintegerrequired
    Replaces the quantity at that location.

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).
201The 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
401unauthorized: the key is missing, wrong or revoked.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
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
429rate_limited: wait the seconds in Retry-After.application/json
Headers
- Retry-After Seconds to wait.
- 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 \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "sku": "TEE-001",
  "external_id": "erp-778",
  "title": "Basic tee",
  "description": "<p>Organic cotton.</p>",
  "status": "active",
  "brand": "Acme",
  "product_type": "T-shirt",
  "category": "Clothing > Tops",
  "attributes": {
    "color": "red",
    "fit": "regular"
  },
  "translations": {
    "it": {
      "title": "Maglietta basic",
      "description": "<p>Cotone biologico.</p>"
    }
  },
  "image_urls": [
    "https://cdn.acme.example/tee-001-front.jpg"
  ],
  "variants": [
    {
      "sku": "TEE-001-M",
      "barcode": "8001234567890",
      "size": "M",
      "weight": 0.2,
      "weight_unit": "kg",
      "prices": [
        {
          "price_list": "eu",
          "price": 19.9,
          "sale_price": 15
        }
      ],
      "stock": [
        {
          "location": "main",
          "available": 7
        }
      ]
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sku": "TEE-001",
    "external_id": "erp-778",
    "title": "Basic tee",
    "description": "<p>Organic cotton.</p>",
    "status": "active",
    "brand": "Acme",
    "product_type": "T-shirt",
    "category": "Clothing > Tops",
    "attributes": {
      "color": "red",
      "fit": "regular"
    },
    "translations": {
      "it": {
        "title": "Maglietta basic",
        "description": "<p>Cotone biologico.</p>"
      }
    },
    "image_urls": [
      "https://cdn.acme.example/tee-001-front.jpg"
    ],
    "variants": [
      {
        "sku": "TEE-001-M",
        "barcode": "8001234567890",
        "size": "M",
        "weight": 0.2,
        "weight_unit": "kg",
        "prices": [
          {
            "price_list": "eu",
            "price": 19.9,
            "sale_price": 15
          }
        ],
        "stock": [
          {
            "location": "main",
            "available": 7
          }
        ]
      }
    ]
  }),
});
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', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'sku' => 'TEE-001',
        'external_id' => 'erp-778',
        'title' => 'Basic tee',
        'description' => '<p>Organic cotton.</p>',
        'status' => 'active',
        'brand' => 'Acme',
        'product_type' => 'T-shirt',
        'category' => 'Clothing > Tops',
        'attributes' => [
            'color' => 'red',
            'fit' => 'regular',
        ],
        'translations' => [
            'it' => [
                'title' => 'Maglietta basic',
                'description' => '<p>Cotone biologico.</p>',
            ],
        ],
        'image_urls' => [
            'https://cdn.acme.example/tee-001-front.jpg',
        ],
        'variants' => [
            [
                'sku' => 'TEE-001-M',
                'barcode' => '8001234567890',
                'size' => 'M',
                'weight' => 0.2,
                'weight_unit' => 'kg',
                'prices' => [
                    [
                        'price_list' => 'eu',
                        'price' => 19.9,
                        'sale_price' => 15,
                    ],
                ],
                'stock' => [
                    [
                        'location' => 'main',
                        'available' => 7,
                    ],
                ],
            ],
        ],
    ],
    '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"
    ]
  }
}

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

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

get/products/{product}

Get a product

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

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

Responses

200The product.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.
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 GET https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001 \
  -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", {
  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', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    '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"
  }
}

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

patch/products/{product}

Update a product

Requires a read and write key.

Writes only the fields you send; everything else stays as it is. The SKU cannot change through the API (sending a different sku is a 400).

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

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

skustring
max length 255pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$
external_idstring
Your id for the product. Remembered per key: later calls can send it instead of sku.

max length 255
titlestring
max length 255
descriptionstring
HTML; unsafe markup is removed.

max length 65000
statusstring
A status code of the catalog (for example active, draft). An unknown code is an error.
product_typestring
Created if new.

max length 255
brandstring
Created if new.

max length 255
categorystring
A category path (Clothing > Tops): added to the product's categories, created if new. To replace all categories use PUT /products/{product}/categories.

max length 500
model_codestring
max length 255
genderstring
max length 255
seasonstring
One or more season codes, comma separated (SS25, FW25).

max length 255
colorstring
max length 255
materialstring
max length 255
made_instring
ISO country code or country name.

max length 255
compositionstring
max length 2000
attribute_setstring
Name or id of the attribute set.
attributesobject
Values by attribute code (GET /attributes). An unknown code is an error.
translationsobject
By locale code (GET /locales). An unknown locale is an error.
image_urlsarray of string (uri)
Linked as they are (not downloaded); a URL already on the product is not added again. To store a copy in Nucleo, use POST /products/{product}/images.

max items 50
variantsarray of VariantInput
max items 500
Attributes of each item
- skustringrequired
  Unique in the whole catalog.
  
  max length 255pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$
- barcodestring
  Unique in the whole catalog.
  
  max length 255
- sizestring
  Size code; becomes the variant's size option (read back in options, as a normalised option code).
  
  max length 255
- costnumber
  min 0
- weightnumber
  min 0
- weight_unitstring
  One ofgkglboz
- pricesarray of PriceInput
  Attributes of each item
  - price_liststringrequired
    Price list code (GET /price-lists).
  - pricenumberrequired
    min 0
  - sale_pricenumber | null
    Discounted price on that list.
    
    min 0
- stockarray of StockInput
  Attributes of each item
  - locationstringrequired
    Location code (GET /locations).
  - availableintegerrequired
    Replaces the quantity at that location.

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
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, 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 \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Basic tee — new season",
  "status": "active"
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Basic tee — new season",
    "status": "active"
  }),
});
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', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'title' => 'Basic tee — new season',
        'status' => 'active',
    ],
    '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": {}
  }
}

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

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

delete/products/{product}

Delete a product

Requires a read and write key.

Moves the product to Nucleo's trash, from where it can be restored for 30 days. Its SKU becomes free for a new product. Not allowed with the field rules inserimento and nucleo (409 field_rule).

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

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

Responses

204Moved to the trash.
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, 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 \
  -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", {
  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', [
    '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 — Moved to the trash.

{
  "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?