Get started with the Commerce API

This API is part of Nucleo Orders. If Orders is not visible in your Nucleo, ask us to enable it for the company.

The Commerce API lets the systems around Nucleo Orders read what happens there: your ERP books orders and refunds, your BI keeps a copy of sales and returns, your customer service sees the status and tracking of an order. With the orders:write scope it can also send orders sold outside the sales channel — by your ERP, a B2B portal or a smaller marketplace.

• Orders, with lines, shipments and tracking, refunds made on the sales channel and a timeline of what happened.
• Returns, with what arrived at the warehouse, in which condition, and the refunds.
• Availability per item and location, with the sales channels' allocation rules if you name a channel.
• Locations: warehouses and stores, with their codes.

To hear about changes instead of polling, use the order webhooks. Warehouses that fulfil orders use the Fulfillment API instead.

1. In Nucleo, go to Commerce > Orders > Channels and logistics.
2. Click New connection and choose Integration (Commerce API) under Integrations.
3. Give it a name (for example the system that will use it) and create it.
4. Copy the endpoint, the API key (nck_…) and the webhook secret (whsec_…): they are shown once. Keep them in your secret store.
5. The connection starts as a draft (403 connection_not_active): in its Status, choose Active and save.

If the key leaks, open the connection and choose More actions > Rotate credentials: the old key and webhook secret stop working at once. Pausing the connection blocks the key (403 connection_paused) until you turn it on again.

A new key can read everything: orders, returns, availability and locations. Each call needs its scope, and GET /ping lists the ones the key has. orders:write is never given by default: ask Nucleo support to enable it on your key.

Send the key as a Bearer token on every call:

curl https://api-commerce.nucleoplatform.com/api/commerce/v1/ping \
  -H "Authorization: Bearer $NUCLEO_COMMERCE_KEY"

const nucleo = async (path) => {
  const res = await fetch(`https://api-commerce.nucleoplatform.com/api/commerce/v1${path}`, {
    headers: { Authorization: `Bearer ${process.env.NUCLEO_COMMERCE_KEY}` },
  });
  const json = await res.json();
  if (!res.ok) throw Object.assign(new Error(json.error.message), json.error, { status: res.status });
  return json;
};

console.log(await nucleo("/ping"));

Every error has the same envelope, with the call's request_id (also in the X-Request-Id header). Branch on code, never on message.

Each key can make 600 calls per minute; ask us if you need more. After 30 calls with a wrong key from the same IP within 5 minutes, that IP is blocked — for every key — until the 5 minutes are over.