Connection

Check that your API key works and see which company it belongs to and what it can read.

Getting a key. In Nucleo, go to Commerce › Orders › Channels and logistics, click New connection and choose Integration (Commerce API) under Integrations. The endpoint, the API key (nck_…) and the webhook secret (whsec_…) are shown once: keep them in your secret store. A new connection is a draft and answers 403 connection_not_active: in its Status, choose Active and save. Rotate credentials in the connection's More actions replaces the key and the webhook secret; the old ones stop working at once. A new key can use every read scope below; orders:write is never given by default: ask Nucleo support to enable it on your key.

Scope	Opens
`orders:read`	Orders, with shipments, refunds and timeline
`returns:read`	Returns, with outcome and refunds
`inventory:read`	Availability per item and location
`locations:read`	Warehouses and stores
`orders:write`	Create orders (`POST /orders`) — only on request

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

Endpoints

get/pingCheck your API key

get/ping

Check your API key

The company and connection your key belongs to, the scopes it has (orders:write only when enabled) and the webhooks it receives. Needs no scope.

GET https://api-commerce.nucleoplatform.com/api/commerce/v1/ping

Authentication: Bearer token

Rate limit: 600 requests per 1m, per connection — Default limit; ask Nucleo support if you need another one.

Responses

200The key works.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- api_versionstringrequired
- companyobjectrequired
  Child attributes
  idinteger
  namestring | null
- connectionobjectrequired
  Child attributes
  idstring
  namestring
  statusstring
- scopesarray of stringrequired
  One oforders:readreturns:readinventory:readlocations:readorders:write
- webhooksobjectrequired
  Child attributes
  enabledbooleanrequired
  A webhook URL is set and the key has a webhook secret. A key created before webhooks existed has no secret: rotate its credentials to get one.
  
  eventsarray of stringrequired
  The events this key receives (empty when webhooks are off).
  
  One oforder.createdorder.status_changedshipment.shippedreturn.createdreturn.status_changed
- server_timestring (date-time)required
401unauthorized: the key is missing or wrong, or the call comes from an IP outside the connection's allowlist.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
403The key is right but cannot do this: insufficient_scope (the key lacks the scope of the call), connection_paused or connection_not_active (the connection is paused or not turned on yet). application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
429rate_limited: wait for the seconds in Retry-After.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- Retry-After Seconds to wait before the next call.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.

Request

curl -X GET https://api-commerce.nucleoplatform.com/api/commerce/v1/ping \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

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

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

Response

{
  "api_version": "v1",
  "company": {
    "id": 1042,
    "name": "Acme Apparel"
  },
  "connection": {
    "id": "6a1f2c3d-4e5b-4c6d-8e7f-9a0b1c2d3e4f",
    "name": "Acme ERP",
    "status": "active"
  },
  "scopes": [
    "orders:read",
    "returns:read",
    "inventory:read",
    "locations:read"
  ],
  "webhooks": {
    "enabled": true,
    "events": [
      "order.created",
      "order.status_changed",
      "shipment.shipped",
      "return.created",
      "return.status_changed"
    ]
  },
  "server_time": "2026-10-13T08:30:00Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the orders:read scope.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests: retry after the number of seconds in Retry-After.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

Was this page helpful?