/

Contents

Bulk

Many products in one call. POST /products/batch (up to 100) answers with the result of each product; POST /imports (up to 5,000) is queued and its progress is read with GET /imports/{id}. Both go through the same checks: an invalid product is reported and skipped, the others are written.

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

Endpoints

post/products/batchCreate or update up to 100 products
post/importsQueue an import of up to 5,000 products
get/imports/{import}Follow an import

post/products/batch

Create or update up to 100 products

Requires a read and write key.

Each product is checked and written on its own, as with POST /products: an invalid product comes back as invalid with its errors and the others are written. A SKU repeated in the same request is invalid (it would not be clear which version wins). The answer lists the products in the order sent.

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

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

productsarray of ProductInputrequired
min items 1max items 100
Attributes of each item
- 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 result of each product.application/json
- dataarray of ItemResultrequired
  Attributes of each item
  indexintegerrequired
  Position in the request, from 0.
  
  skustring | nullrequired
  product_idinteger | null
  statusstringrequired
  invalid: not written because the input is wrong. failed: nothing could be written.
  
  One ofcreatedupdatedpartialskippedfailedinvalid
  errorsarray of objectrequired
  Attributes of each item
  fieldstring
  For invalid, the field in error.
  
  variant_skustring | null
  messagestring
  notesarray of stringrequired
- summarySummaryrequired
  Child attributes
  createdinteger
  updatedinteger
  partialinteger
  skippedinteger
  failedinteger
  invalidinteger
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

Request

curl -X POST https://api-catalog.nucleoplatform.com/api/catalog/v1/products/batch \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "products": [
    {
      "sku": "TEE-001",
      "title": "Basic tee",
      "variants": [
        {
          "sku": "TEE-001-M",
          "prices": [
            {
              "price_list": "eu",
              "price": 19.9
            }
          ]
        }
      ]
    },
    {
      "sku": "TEE-002",
      "title": "Pocket tee"
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "products": [
      {
        "sku": "TEE-001",
        "title": "Basic tee",
        "variants": [
          {
            "sku": "TEE-001-M",
            "prices": [
              {
                "price_list": "eu",
                "price": 19.9
              }
            ]
          }
        ]
      },
      {
        "sku": "TEE-002",
        "title": "Pocket tee"
      }
    ]
  }),
});
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/batch', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'products' => [
            [
                'sku' => 'TEE-001',
                'title' => 'Basic tee',
                'variants' => [
                    [
                        'sku' => 'TEE-001-M',
                        'prices' => [
                            [
                                'price_list' => 'eu',
                                'price' => 19.9,
                            ],
                        ],
                    ],
                ],
            ],
            [
                'sku' => 'TEE-002',
                'title' => 'Pocket tee',
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": [
    {
      "index": 0,
      "sku": "TEE-001",
      "product_id": 1201,
      "status": "created",
      "errors": [],
      "notes": []
    },
    {
      "index": 1,
      "sku": "TEE-002",
      "product_id": 1202,
      "status": "updated",
      "errors": [],
      "notes": []
    }
  ],
  "summary": {
    "created": 1,
    "updated": 1,
    "partial": 0,
    "skipped": 0,
    "failed": 0,
    "invalid": 0
  }
}

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

post/imports

Queue an import of up to 5,000 products

Requires a read and write key.

The products are checked at once (invalid ones are reported in the results and not written), then written in the background in groups of 100. Follow the progress with GET /imports/{id}. Usually it starts within a minute.

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

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

productsarray of ProductInputrequired
min items 1max items 5000
Attributes of each item
- 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

202Accepted and queued.application/json
Headers
- Location Where to follow the import.
- dataImportrequired
  Child attributes
  idstring (uuid)required
  statusstringrequired
  One ofqueuedprocessingdonepartialfailed
  totalintegerrequired
  processedintegerrequired
  failedintegerrequired
  Products invalid or failed.
  
  created_atstring (date-time)
  started_atstring (date-time) | null
  finished_atstring (date-time) | 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
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
413payload_too_large: the body is larger than 20 MB.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/imports \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "products": [
    {
      "sku": "string",
      "external_id": "string",
      "title": "string",
      "description": "string",
      "status": "string",
      "product_type": "string",
      "brand": "string",
      "category": "string",
      "model_code": "string",
      "gender": "string",
      "season": "string",
      "color": "string",
      "material": "string",
      "made_in": "string",
      "composition": "string",
      "attribute_set": "string",
      "attributes": {},
      "translations": {},
      "image_urls": [
        "https://shop.acme.example"
      ],
      "variants": [
        {
          "sku": "string",
          "barcode": "string",
          "size": "string",
          "cost": 0,
          "weight": 0,
          "weight_unit": "g",
          "prices": [
            {}
          ],
          "stock": [
            {}
          ]
        }
      ]
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/imports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "products": [
      {
        "sku": "string",
        "external_id": "string",
        "title": "string",
        "description": "string",
        "status": "string",
        "product_type": "string",
        "brand": "string",
        "category": "string",
        "model_code": "string",
        "gender": "string",
        "season": "string",
        "color": "string",
        "material": "string",
        "made_in": "string",
        "composition": "string",
        "attribute_set": "string",
        "attributes": {},
        "translations": {},
        "image_urls": [
          "https://shop.acme.example"
        ],
        "variants": [
          {
            "sku": "string",
            "barcode": "string",
            "size": "string",
            "cost": 0,
            "weight": 0,
            "weight_unit": "g",
            "prices": [
              {}
            ],
            "stock": [
              {}
            ]
          }
        ]
      }
    ]
  }),
});
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/imports', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'products' => [
            [
                'sku' => 'string',
                'external_id' => 'string',
                'title' => 'string',
                'description' => 'string',
                'status' => 'string',
                'product_type' => 'string',
                'brand' => 'string',
                'category' => 'string',
                'model_code' => 'string',
                'gender' => 'string',
                'season' => 'string',
                'color' => 'string',
                'material' => 'string',
                'made_in' => 'string',
                'composition' => 'string',
                'attribute_set' => 'string',
                'attributes' => (object) [],
                'translations' => (object) [],
                'image_urls' => [
                    'https://shop.acme.example',
                ],
                'variants' => [
                    [
                        'sku' => 'string',
                        'barcode' => 'string',
                        'size' => 'string',
                        'cost' => 0,
                        'weight' => 0,
                        'weight_unit' => 'g',
                        'prices' => [
                            (object) [],
                        ],
                        'stock' => [
                            (object) [],
                        ],
                    ],
                ],
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
    "status": "queued",
    "total": 1,
    "processed": 1,
    "failed": 1,
    "created_at": "2026-10-01T09:30:00Z",
    "started_at": "2026-10-01T09:30:00Z",
    "finished_at": "2026-10-01T09:30:00Z"
  }
}

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

get/imports/{import}

Follow an import

Progress and, product by product, the results so far. Only imports created with the same key.

GET https://api-catalog.nucleoplatform.com/api/catalog/v1/imports/{import}

Authentication: Bearer token

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

Path parameters

importstring (uuid)required

Responses

200The import.application/json
- dataImport & objectrequired
  Child attributes
  idstring (uuid)required
  statusstringrequired
  One ofqueuedprocessingdonepartialfailed
  totalintegerrequired
  processedintegerrequired
  failedintegerrequired
  Products invalid or failed.
  
  created_atstring (date-time)
  started_atstring (date-time) | null
  finished_atstring (date-time) | null
  resultsarray of ItemResult
  Attributes of each item
  indexintegerrequired
  Position in the request, from 0.
  
  skustring | nullrequired
  product_idinteger | null
  statusstringrequired
  invalid: not written because the input is wrong. failed: nothing could be written.
  
  One ofcreatedupdatedpartialskippedfailedinvalid
  errorsarray of objectrequired
  Attributes of each item
  fieldstring
  For invalid, the field in error.
  
  variant_skustring | null
  messagestring
  notesarray of stringrequired
  summarySummary
  Child attributes
  createdinteger
  updatedinteger
  partialinteger
  skippedinteger
  failedinteger
  invalidinteger
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/imports/{import}' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/imports/{import}", {
  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/imports/{import}', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
    "status": "queued",
    "total": 1,
    "processed": 1,
    "failed": 1,
    "created_at": "2026-10-01T09:30:00Z",
    "started_at": "2026-10-01T09:30:00Z",
    "finished_at": "2026-10-01T09:30:00Z",
    "results": [
      {
        "index": 1,
        "sku": "string",
        "product_id": 1,
        "status": "created",
        "errors": [
          {
            "field": "string",
            "variant_sku": "string",
            "message": "string"
          }
        ],
        "notes": [
          "string"
        ]
      }
    ],
    "summary": {
      "created": 1,
      "updated": 1,
      "partial": 1,
      "skipped": 1,
      "failed": 1,
      "invalid": 1
    }
  }
}

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

Was this page helpful?