/

Contents

CatalogCatalog API · v1

Variants

Variants of a product, addressed by their id or sku.

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

Endpoints

get/products/{product}/variantsList the variants of a product
post/products/{product}/variantsAdd or update a variant
patch/products/{product}/variants/{variant}Update a variant
DEL/products/{product}/variants/{variant}Delete a variant

get/products/{product}/variants

List the variants of a product

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

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 variants.application/json
- dataarray of Variantrequired
  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
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/variants \
  -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/variants", {
  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/variants', [
    '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",
      "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
        }
      ]
    }
  ]
}

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

post/products/{product}/variants

Add or update a variant

Requires a read and write key.

Creates the variant (201) or updates the variant of this product with the same SKU (200).

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

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

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 variant as it is now, and what happened.application/json
- dataVariantrequired
  Child attributes
  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
- 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 variant as it is now, and what happened.application/json
- dataVariantrequired
  Child attributes
  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
- 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

Request

curl -X POST https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/variants \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "sku": "string",
  "barcode": "string",
  "size": "string",
  "cost": 0,
  "weight": 0,
  "weight_unit": "g",
  "prices": [
    {
      "price_list": "string",
      "price": 0,
      "sale_price": 0
    }
  ],
  "stock": [
    {
      "location": "string",
      "available": 1
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/variants", {
  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": "string",
    "barcode": "string",
    "size": "string",
    "cost": 0,
    "weight": 0,
    "weight_unit": "g",
    "prices": [
      {
        "price_list": "string",
        "price": 0,
        "sale_price": 0
      }
    ],
    "stock": [
      {
        "location": "string",
        "available": 1
      }
    ]
  }),
});
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/variants', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'sku' => 'string',
        'barcode' => 'string',
        'size' => 'string',
        'cost' => 0,
        'weight' => 0,
        'weight_unit' => 'g',
        'prices' => [
            [
                'price_list' => 'string',
                'price' => 0,
                'sale_price' => 0,
            ],
        ],
        'stock' => [
            [
                'location' => 'string',
                'available' => 1,
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": {
    "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
      }
    ]
  },
  "result": {
    "status": "created",
    "errors": [
      {
        "variant_sku": "string",
        "message": "string"
      }
    ],
    "notes": [
      "string"
    ]
  }
}

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

patch/products/{product}/variants/{variant}

Update a variant

Requires a read and write key.

Only the fields sent change. The SKU cannot change through the API.

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

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
variantstringrequired
Variant id or SKU.

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
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 variant as it is now, and what happened.application/json
- dataVariantrequired
  Child attributes
  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
- 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 PATCH 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/variants/{variant}' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "sku": "string",
  "barcode": "string",
  "size": "string",
  "cost": 0,
  "weight": 0,
  "weight_unit": "g",
  "prices": [
    {
      "price_list": "string",
      "price": 0,
      "sale_price": 0
    }
  ],
  "stock": [
    {
      "location": "string",
      "available": 1
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/variants/{variant}", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sku": "string",
    "barcode": "string",
    "size": "string",
    "cost": 0,
    "weight": 0,
    "weight_unit": "g",
    "prices": [
      {
        "price_list": "string",
        "price": 0,
        "sale_price": 0
      }
    ],
    "stock": [
      {
        "location": "string",
        "available": 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/variants/{variant}', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'sku' => 'string',
        'barcode' => 'string',
        'size' => 'string',
        'cost' => 0,
        'weight' => 0,
        'weight_unit' => 'g',
        'prices' => [
            [
                'price_list' => 'string',
                'price' => 0,
                'sale_price' => 0,
            ],
        ],
        'stock' => [
            [
                'location' => 'string',
                'available' => 1,
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

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

delete/products/{product}/variants/{variant}

Delete a variant

Requires a read and write key.

Deletes the variant with its prices and stock. Not allowed with the field rules inserimento and nucleo.

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

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
variantstringrequired
Variant id or SKU.

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/variants/{variant}' \
  -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/variants/{variant}", {
  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/variants/{variant}', [
    '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?