Load your products

Send up to 100 products per call to POST /products/batch. Each product is checked and written on its own: an invalid one comes back as invalid with its errors, the others are written.

curl -X POST https://api-catalog.nucleoplatform.com/api/catalog/v1/products/batch \
  -H "Authorization: Bearer $NUCLEO_CATALOG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: load-2026-10-14-part-1" \
  -d '{
  "products": [
    {
      "sku": "TEE-001",
      "external_id": "erp-778",
      "title": "Basic tee",
      "description": "<p>Organic cotton.</p>",
      "status": "active",
      "brand": "Acme",
      "category": "Clothing > Tops",
      "attributes": { "color": "red", "fit": "regular" },
      "translations": { "it": { "title": "Maglietta basic" } },
      "variants": [
        {
          "sku": "TEE-001-M",
          "barcode": "8001234567890",
          "size": "M",
          "prices": [{ "price_list": "eu", "price": 19.9, "sale_price": 15 }],
          "stock": [{ "location": "main", "available": 7 }]
        }
      ]
    }
  ]
}'

The answer has one result per product, in the order you sent them:

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

• partial: some variants could not be written (see errors), the rest was.
• skipped: your key's field rule left nothing to write.
• notes explains fields that were not written — for example a field another connected system owns.

More than 100 products? Queue them with POST /imports (up to 5,000 per call). The answer is 202 with the import id; follow it with GET /imports/{id} until status is done, partial or failed. Products are written in groups of 100 and the results fill in as they go. Usually an import starts within a minute.

Good to know

• Only the fields you send are written. An absent or empty field never clears a value in Nucleo.
• Variants, prices and stock are added or updated, never removed by omission. To delete a variant use DELETE /products/{product}/variants/{variant}; to delete a product, DELETE /products/{product} (it goes to Nucleo's trash, restorable for 30 days).
• external_id is your own id. Nucleo remembers it for your key: later you can send it instead of sku to find the product, and it comes back in every read.
• image_urls are linked as they are. To have Nucleo download and store an image, use POST /products/{product}/images with its url (or upload the file).
• One request can carry up to 20 MB.