Connection

Check that your API key works and see which company, connection and locations it opens.

Getting a key. Nucleo sets up a Fulfillment API connection for your warehouse with the merchant and links the locations you serve to it. The endpoint, the API key (nfk_…) and the webhook secret (whsec_…) are shown once; rotating the credentials replaces both at once. A new connection is a draft and answers 403 connection_not_active until it is turned on.

Base URL. Call the endpoint shown with the credentials: it can be the connection's own host instead of the default server below.

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

Endpoints

get/pingCheck your API key

get/ping

Check your API key

The company, the connection and the locations your key opens, who makes the carrier labels and whether webhooks are on. Safe to call at any time.

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

Authentication: Bearer token

Rate limit: 600 requests per 1m, per connection — Default limit; the merchant can set another one on the connection.

Responses

200The key works.application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- api_version"v1"
- companyobject
  Child attributes
  idinteger
  namestring | null
- connectionobject
  Child attributes
  idstring (uuid)
  namestring
  statusstring
  error while Nucleo considers the warehouse silent; your next call clears it.
  
  One ofactiveerror
- locationsarray of object
  Nucleo locations your warehouse serves.
  Attributes of each item
  codestring
  namestring
  stock_location_codesarray of string
  Codes to use as location_code in stock updates.
- labels_bystring
  One ofnucleowarehouse
- webhooksobject
  Child attributes
  enabledboolean
- server_timestring (date-time)
401Missing or invalid API key (unauthorized).application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
403The connection is paused (connection_paused) or not active yet (connection_not_active). Nothing was read or changed: retry later. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
429rate_limited: more calls in a minute than the connection allows (600 by default, all endpoints together; the merchant can set another limit), or too many failed authentications from your IP. Wait the seconds in Retry-After. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Retry-After Seconds to wait before retrying.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.

Request

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

const res = await fetch("https://api-commerce.nucleoplatform.com/api/fulfillment/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/fulfillment/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 Logistics Verona",
    "status": "active"
  },
  "locations": [
    {
      "code": "VRN",
      "name": "Verona warehouse",
      "stock_location_codes": [
        "VR1"
      ]
    }
  ],
  "labels_by": "warehouse",
  "webhooks": {
    "enabled": true
  },
  "server_time": "2026-10-13T08:30:00Z"
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "0b6c3e4f-1a2d-4c5b-8e7f-9a0b1c2d3e4f"
  }
}

{
  "error": {
    "code": "connection_paused",
    "message": "This connection is paused: nothing was changed.",
    "request_id": "3c2b1a0f-9e8d-4c7b-a6f5-4e3d2c1b0a9f"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests: retry after the number of seconds in Retry-After.",
    "request_id": "4f3e2d1c-0b9a-4f8e-8d7c-6b5a4f3e2d1c"
  }
}

Was this page helpful?