/

Contents

Prices and stock

The two most frequent updates, per product or in bulk by variant SKU (up to 1,000 lines). Only the price lists and locations you send change.

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

Endpoints

put/products/{product}/pricesSet prices of a product
put/products/{product}/stockSet stock of a product
put/pricesSet prices in bulk
put/stockSet stock in bulk

put/products/{product}/prices

Set prices of a product

Requires a read and write key.

One line per variant and price list (up to 500). Price lists not sent do not change.

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

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

pricesarray of object & PriceInputrequired
min items 1max items 500
Attributes of each item
- variant_skustringrequired
  SKU of a variant of this product.
- price_liststringrequired
  Price list code (GET /price-lists).
- pricenumberrequired
  min 0
- sale_pricenumber | null
  Discounted price on that list.
  
  min 0

Responses

200All variants of the product as they are now, and what happened.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
- resultWriteResultrequired
  Child attributes
  statusstringrequired
  partial: some variants could not be written (see errors), the rest was. skipped: the key's field rule left nothing to write.
  
  One ofcreatedupdatedpartialskipped
  errorsarray of objectrequired
  Attributes of each item
  variant_skustring | null
  messagestring
  notesarray of stringrequired
  Fields not written and why (field rule, field owned by another system).
400The request must change: validation_failed (see details, one list of messages per field), invalid_json, invalid_cursor, product_not_written, variant_not_written, not_written, image_not_downloadable. application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_not_found, or not_found for a path that does not exist.application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject

Request

curl -X PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/prices \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "prices": [
    {
      "variant_sku": "TEE-001-M",
      "price_list": "eu",
      "price": 19.9,
      "sale_price": 15
    },
    {
      "variant_sku": "TEE-001-L",
      "price_list": "eu",
      "price": 19.9
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/prices", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prices": [
      {
        "variant_sku": "TEE-001-M",
        "price_list": "eu",
        "price": 19.9,
        "sale_price": 15
      },
      {
        "variant_sku": "TEE-001-L",
        "price_list": "eu",
        "price": 19.9
      }
    ]
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/prices', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'prices' => [
            [
                'variant_sku' => 'TEE-001-M',
                'price_list' => 'eu',
                'price' => 19.9,
                'sale_price' => 15,
            ],
            [
                'variant_sku' => 'TEE-001-L',
                'price_list' => 'eu',
                'price' => 19.9,
            ],
        ],
    ],
    '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": {}
  }
}

put/products/{product}/stock

Set stock of a product

Requires a read and write key.

One line per variant and location (up to 500): available replaces the quantity (and the on-hand quantity) at that location. Locations not sent do not change.

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

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

stockarray of object & StockInputrequired
min items 1max items 500
Attributes of each item
- variant_skustringrequired
- locationstringrequired
  Location code (GET /locations).
- availableintegerrequired
  Replaces the quantity at that location.

Responses

200All variants of the product as they are now, and what happened.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
- resultWriteResultrequired
  Child attributes
  statusstringrequired
  partial: some variants could not be written (see errors), the rest was. skipped: the key's field rule left nothing to write.
  
  One ofcreatedupdatedpartialskipped
  errorsarray of objectrequired
  Attributes of each item
  variant_skustring | null
  messagestring
  notesarray of stringrequired
  Fields not written and why (field rule, field owned by another system).
400The request must change: validation_failed (see details, one list of messages per field), invalid_json, invalid_cursor, product_not_written, variant_not_written, not_written, image_not_downloadable. application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject
404product_not_found, variant_not_found, image_not_found, import_not_found, webhook_not_found, or not_found for a path that does not exist.application/json
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable machine-readable code. Branch on it, not on the message.
  
  messagestringrequired
  request_idstringrequired
  Same as the X-Request-Id header. Quote it to support.
  
  detailsobject

Request

curl -X PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/stock \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "stock": [
    {
      "variant_sku": "TEE-001-M",
      "location": "main",
      "available": 12
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/stock", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "stock": [
      {
        "variant_sku": "TEE-001-M",
        "location": "main",
        "available": 12
      }
    ]
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/products/TEE-001/stock', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'stock' => [
            [
                'variant_sku' => 'TEE-001-M',
                'location' => 'main',
                'available' => 12,
            ],
        ],
    ],
    '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": {}
  }
}

put/prices

Set prices in bulk

Requires a read and write key.

Up to 1,000 lines, each for one variant SKU of any product. The answer has one result per line, in order.

PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/prices

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

pricesarray of object & PriceInputrequired
min items 1max items 1000
Attributes of each item
- skustringrequired
  Variant SKU.
- price_liststringrequired
  Price list code (GET /price-lists).
- pricenumberrequired
  min 0
- sale_pricenumber | null
  Discounted price on that list.
  
  min 0

Responses

200One result per line, in the order sent.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
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 PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/prices \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "prices": [
    {
      "sku": "TEE-001-M",
      "price_list": "eu",
      "price": 21,
      "sale_price": null
    },
    {
      "sku": "TEE-002-S",
      "price_list": "us",
      "price": 25
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/prices", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prices": [
      {
        "sku": "TEE-001-M",
        "price_list": "eu",
        "price": 21,
        "sale_price": null
      },
      {
        "sku": "TEE-002-S",
        "price_list": "us",
        "price": 25
      }
    ]
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/prices', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'prices' => [
            [
                'sku' => 'TEE-001-M',
                'price_list' => 'eu',
                'price' => 21,
                'sale_price' => null,
            ],
            [
                'sku' => 'TEE-002-S',
                'price_list' => 'us',
                'price' => 25,
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": [
    {
      "index": 1,
      "sku": "string",
      "product_id": 1,
      "status": "created",
      "errors": [
        {
          "field": "string",
          "variant_sku": "string",
          "message": "string"
        }
      ],
      "notes": [
        "string"
      ]
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid: see details.",
    "request_id": "7c0f8a1e-3b2d-4e5f-9a6b-1c2d3e4f5a6b",
    "details": {
      "variants.0.prices.0.price_list": [
        "Unknown price list \"usa\". GET /price-lists lists them."
      ]
    }
  }
}

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

put/stock

Set stock in bulk

Requires a read and write key.

Up to 1,000 lines, each for one variant SKU and one location. The answer has one result per line, in order.

PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/stock

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

stockarray of object & StockInputrequired
min items 1max items 1000
Attributes of each item
- skustringrequired
  Variant SKU.
- locationstringrequired
  Location code (GET /locations).
- availableintegerrequired
  Replaces the quantity at that location.

Responses

200One result per line, in the order sent.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
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 PUT https://api-catalog.nucleoplatform.com/api/catalog/v1/stock \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44' \
  -H 'Content-Type: application/json' \
  -d '{
  "stock": [
    {
      "sku": "TEE-001-M",
      "location": "main",
      "available": 12
    },
    {
      "sku": "TEE-001-L",
      "location": "main",
      "available": 0
    }
  ]
}'

const res = await fetch("https://api-catalog.nucleoplatform.com/api/catalog/v1/stock", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "stock": [
      {
        "sku": "TEE-001-M",
        "location": "main",
        "available": 12
      },
      {
        "sku": "TEE-001-L",
        "location": "main",
        "available": 0
      }
    ]
  }),
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-catalog.nucleoplatform.com/api/catalog/v1/stock', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2b5c0d2e-7d2a-4f6e-9a51-0c8a1e7f3b44',
    ],
    'json' => [
        'stock' => [
            [
                'sku' => 'TEE-001-M',
                'location' => 'main',
                'available' => 12,
            ],
            [
                'sku' => 'TEE-001-L',
                'location' => 'main',
                'available' => 0,
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": [
    {
      "index": 1,
      "sku": "string",
      "product_id": 1,
      "status": "created",
      "errors": [
        {
          "field": "string",
          "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": {}
  }
}

Was this page helpful?