/

Contents

CommerceStableVersion v1

Commerce API

Read orders, returns, availability and locations from Nucleo Orders, and send in orders — for your ERP, BI, B2B and customer service tools.

The API for the systems that work next to Nucleo Orders: your ERP, your data warehouse, your customer service desk, your own apps — and for the ones that sell outside the sales channel (an ERP, a B2B portal, a smaller marketplace) and send their orders to Nucleo. One API key per integration: the key belongs to one company and only does what its permissions (scopes) allow.

Warehouses that fulfil orders use the Fulfillment API instead.

Conventions

JSON in UTF-8, snake_case field names, dates in ISO 8601 UTC (2026-10-13T08:30:00Z).
Amounts are decimal strings with their currency: {"amount": "180.00", "currency": "EUR"}.
Lists are paginated with an opaque cursor: limit (1–200, default 50), answer {data, next_cursor}. Follow next_cursor until it is null. Lists are sorted by last update, oldest first: keep the updated_at of the last item you read and pass it as updated_since next time to read only what changed.
Every response carries X-Request-Id. Errors always have the same shape: {"error": {"code", "message", "request_id", "details"}}.
Order numbers are the merchant's (#1042). In paths you can omit the # or encode it as %23, or use the order id.
Reads never change anything. The only write is POST /orders, which creates an order and needs the orders:write scope; it accepts an Idempotency-Key.
Optional signed webhooks tell you when an order or a return changes, so you read it right away instead of waiting for your next sync.

Authentication

apiKeyHTTP bearer
The connection's API key (nck_…): Authorization: Bearer <api_key>.
webhookSignatureAPI key · header · X-Nucleo-Signature
Webhooks Nucleo sends to your webhook URL. X-Nucleo-Signature: t=<unix time>,v1=<signature>, where the signature is the lowercase hex HMAC-SHA256 of <t>.<raw body> keyed with the connection's webhook secret (whsec_…). Verify it on the exact bytes you received, in constant time, and reject a t more than 5 minutes away from your clock. The event type is also in X-Nucleo-Event.

Base URL: https://api-commerce.nucleoplatform.com/api/commerce/v1Production
Who calls it: Your servers
Endpoints: 9 + 5 webhook
OpenAPI 3.1 specification: commerce.yaml

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

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"
  }
}

Orders

Orders as the customer and your back office see them, with their lines, shipments, refunds made on the sales channel and the returns opened on them.

Status	Meaning
`received`	Arrived from the sales channel or through this API, not yet sent to fulfilment.
`on_hold`	Stopped by the merchant or by a rule (for example a payment check).
`in_fulfillment`	Assigned to a warehouse or store, which is preparing it.
`shipped`	Every parcel has left.
`delivered`	The carrier delivered it.
`cancellation_requested`	Cancelled after the warehouse took it over: waiting for the warehouse to stop it.
`cancelled`	Cancelled.

Fields that stay inside Nucleo — internal notes, carrier costs, routing decisions, holds' details, customer tags and payment transactions — are not part of the API.

Sending orders. With orders:write your system creates orders with POST /orders. They go through the same steps as the sales channel's: Nucleo's routing rules choose the location, the warehouse receives them, and order.created is sent to every key that listens. Send orders ready to ship: they are treated as paid.

get/orders

List orders

Orders sorted by last update, oldest first. Scope orders:read.

To keep a copy in sync, read every page once, then call again with updated_since set to the updated_at of the last order you stored. A change to a return does not update its order: sync returns with GET /returns.

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

Authentication: Bearer token

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

Query parameters

statusstring
Only orders in this status.

One ofreceivedon_holdin_fulfillmentshippeddeliveredcancellation_requestedcancelled
Example: received
updated_sincestring (date-time)
Only items updated at or after this time (ISO 8601). Encode + as %2B if you send an offset.

Example: 2026-10-13T08:00:00Z
cursorstring
The next_cursor of the previous page. Keep status and updated_since the same; a different status answers 400 invalid_cursor.
limitinteger
Items per page.

min 1max 200default 50
Example: 50

Responses

200A page of orders.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- dataarray of Orderrequired
  Attributes of each item
  idstring (uuid)required
  numberstringrequired
  Example: #1042
  statusstringrequired
  One ofreceivedon_holdin_fulfillmentshippeddeliveredcancellation_requestedcancelled
  channelstring | null
  Where the order comes from, for example shopify; nucleo_api for orders created with POST /orders.
  
  placed_atstring (date-time) | null
  updated_atstring (date-time) | null
  payment_statusstring | null
  One ofpendingauthorizedpaidcapturedpartially_refundedrefundedvoidedexpirednull
  on_holdboolean
  customerobject
  Child attributes
  namestring | null
  emailstring | null
  phonestring | null
  shipping_addressAddress
  Child attributes
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
  billing_addressAddress | null
  Address
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
  shippingobject
  The shipping method the customer chose.
  
  Child attributes
  method_codestring | null
  method_namestring | null
  currencystring
  totalsobject
  current_total is the total after edits and cancellations; refunded what was refunded on the sales channel.
  
  Child attributes
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  discountsMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  taxMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  current_totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  refundedMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of OrderLinerequired
  Attributes of each item
  line_idstring
  skustring | null
  barcodestring | null
  titlestring | null
  quantityinteger
  quantity_cancelledinteger
  quantity_shippedinteger
  unit_priceMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  tax_ratestring
  Percentage as a decimal string, for example 22.00.
  
  shipmentsarray of Shipment
  Attributes of each item
  idstring
  statusstring
  One oflabel_createdconfirmedshippeddeliveredvoided
  location_codestring | null
  The location that shipped it.
  
  carrierobject
  Child attributes
  codestring | null
  namestring | null
  servicestring | null
  tracking_urlstring | null
  tracking_numbersarray of string
  shipped_atstring (date-time) | null
  delivered_atstring (date-time) | null
  linesarray of object
  Attributes of each item
  line_idstring | null
  quantityinteger
  refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  returnsarray of object
  The returns opened on the order; read each one with GET /returns/{return}.
  
  Attributes of each item
  idstring
  numberstring | null
  statusstring
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
  cancellationobject | null
  Present when the order is cancelled or its cancellation is requested.
  
  object
  reasonstring | null
  cancelled_atstring (date-time) | null
- next_cursorstring | nullrequired
400The request is not valid: validation_failed (with details per parameter or field), invalid_cursor, invalid_json (the body is not a JSON object) or unknown_item (with details per line, for example lines.0). 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.
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/orders?status=received&updated_since=2026-10-13T08%3A00%3A00Z&limit=50' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/commerce/v1/orders?status=received&updated_since=2026-10-13T08%3A00%3A00Z&limit=50", {
  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/orders?status=received&updated_since=2026-10-13T08%3A00%3A00Z&limit=50', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": [
    {
      "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
      "number": "#1042",
      "status": "received",
      "channel": "string",
      "placed_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z",
      "payment_status": "pending",
      "on_hold": true,
      "customer": {
        "name": "string",
        "email": "string",
        "phone": "string"
      },
      "shipping_address": {
        "first_name": "string",
        "last_name": "string",
        "company": "string",
        "address1": "string",
        "address2": "string",
        "city": "string",
        "postal_code": "string",
        "province_code": "string",
        "country_code": "string",
        "phone": "string"
      },
      "billing_address": {
        "first_name": "string",
        "last_name": "string",
        "company": "string",
        "address1": "string",
        "address2": "string",
        "city": "string",
        "postal_code": "string",
        "province_code": "string",
        "country_code": "string",
        "phone": "string"
      },
      "shipping": {
        "method_code": "string",
        "method_name": "string"
      },
      "currency": "string",
      "totals": {
        "subtotal": {
          "amount": "180.00",
          "currency": "EUR"
        },
        "discounts": {
          "amount": "180.00",
          "currency": "EUR"
        },
        "shipping": {
          "amount": "180.00",
          "currency": "EUR"
        },
        "tax": {
          "amount": "180.00",
          "currency": "EUR"
        },
        "total": {
          "amount": "180.00",
          "currency": "EUR"
        },
        "current_total": {
          "amount": "180.00",
          "currency": "EUR"
        },
        "refunded": {
          "amount": "180.00",
          "currency": "EUR"
        }
      },
      "lines": [
        {
          "line_id": "string",
          "sku": "string",
          "barcode": "string",
          "title": "string",
          "quantity": 1,
          "quantity_cancelled": 1,
          "quantity_shipped": 1,
          "unit_price": {
            "amount": "180.00",
            "currency": "EUR"
          },
          "total": {
            "amount": "180.00",
            "currency": "EUR"
          },
          "tax_rate": "string"
        }
      ],
      "shipments": [
        {
          "id": "string",
          "status": "label_created",
          "location_code": "string",
          "carrier": {
            "code": "string",
            "name": "string",
            "service": "string"
          },
          "tracking_url": "string",
          "tracking_numbers": [
            "string"
          ],
          "shipped_at": "2026-10-01T09:30:00Z",
          "delivered_at": "2026-10-01T09:30:00Z",
          "lines": [
            {}
          ]
        }
      ],
      "refunds": [
        {
          "id": "string",
          "return_id": "string",
          "refunded_at": "2026-10-01T09:30:00Z",
          "total": {
            "amount": "180.00",
            "currency": "EUR"
          },
          "shipping": {
            "amount": "180.00",
            "currency": "EUR"
          },
          "lines": [
            {}
          ]
        }
      ],
      "returns": [
        {
          "id": "string",
          "number": "string",
          "status": "requested"
        }
      ],
      "cancellation": {
        "reason": "string",
        "cancelled_at": "2026-10-01T09:30:00Z"
      }
    }
  ],
  "next_cursor": "string"
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c",
    "details": {
      "status": [
        "Must be one of: received, on_hold, in_fulfillment, shipped, delivered, cancellation_requested, cancelled."
      ]
    }
  }
}

{
  "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"
  }
}

post/orders

Create an order

Sends an order from your system to Nucleo. Scope orders:write.

No duplicates. channel_order_ref is your own id of the order. Sending the same channel_order_ref again with the same key creates nothing: the answer is 200 with the order created the first time, unchanged. The body is still validated, but its content is not applied. Use it to recover an answer you lost. References are per key: another key can use the same one.
Number. Nucleo shows the order as API- followed by your number (B2B-871 becomes API-B2B-871), so it never clashes with the sales channel's numbers; read it with GET /orders/API-B2B-871. number may use letters, digits, ., - and _, at most 40 characters. Without it, channel_order_ref is used and must follow the same rule (400 validation_failed on number otherwise). A number another order already has answers 409 number_taken — for example two keys sending the same channel_order_ref without a number.
Items. Every line needs the sku or the barcode of an item Nucleo knows, with a barcode; with both, they must be the same item. Unknown or mismatched items reject the whole order with 400 unknown_item, one message per line in details (lines.0, lines.1, …).
Amounts are in EUR, tax included; currency can only be EUR. Every line needs its tax_rate, and shipping.tax_rate is required with shipping.price. Nucleo computes subtotal (sum of unit_price × quantity), tax (the tax of the lines and of the shipping), total (subtotal plus shipping.price); discounts is 0: send prices already discounted.
Dates. placed_at can carry any offset; Nucleo stores and returns it in UTC.
What happens next. The order is treated as paid. Nucleo's routing rules choose the location. If no rule covers the order, or no location of its rule has all the items in stock, it stays on_hold until the merchant adds or fixes the rule and routes it again. notes reaches the merchant and the warehouse with the order. order.created is sent to every key that receives webhooks, yours included, always with status: received; the status it reaches next comes with order.status_changed.

Orders created here cannot be changed or cancelled through the API yet: ask the merchant.

POST https://api-commerce.nucleoplatform.com/api/commerce/v1/orders

Authentication: Bearer token

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

Headers

Idempotency-Keystring
Any unique string you generate (1–255 printable ASCII characters, no spaces), for example a UUID. For 48 hours, the same key with the same body returns the stored answer without doing the work again (header Idempotent-Replayed: true; the replayed body is the original one). The same key with a different body answers 409 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_progress. A key left in progress for more than 2 minutes (an interrupted call) is free again. Keys are per connection. The body is compared byte by byte: resend exactly the same bytes. Server errors (5xx) and 429 are not stored: retry them with the same key. Other errors (4xx) are stored too: after fixing the request, send it with a new key. Without a key, channel_order_ref still prevents duplicates.

max length 255

Request bodyapplication/json

channel_order_refstringrequired
Your id of the order (printable ASCII, no spaces). Unique per key; sending it again returns the existing order.

max length 120pattern ^[!-~]+$
numberstring
Shown in Nucleo and to the warehouse as API- plus this value. Default channel_order_ref, which must then follow the same pattern.

max length 40pattern ^[A-Za-z0-9][A-Za-z0-9._-]*$
placed_atstring (date-time)
When the customer placed it, with any offset; stored in UTC. Default now.
currencystring
Only EUR. Default EUR.

One ofEUR
customerobjectrequired
Child attributes
- namestring
  Default the shipping address's first and last name.
  
  max length 255
- emailstring (email)required
  max length 255
- phonestring
  Default the shipping address's phone.
  
  max length 40
shipping_addressAddressInputrequired
Child attributes
- first_namestring
  max length 120
- last_namestring
  max length 120
- companystring
  max length 120
- address1stringrequired
  max length 255
- address2string
  max length 255
- citystringrequired
  max length 120
- postal_codestring
  max length 20
- province_codestring
  max length 10
- country_codestringrequired
  ISO 3166-1 alpha-2 (IT; lowercase is accepted).
  
  min length 2max length 2
- phonestring
  max length 40
billing_addressAddressInput
Child attributes
- first_namestring
  max length 120
- last_namestring
  max length 120
- companystring
  max length 120
- address1stringrequired
  max length 255
- address2string
  max length 255
- citystringrequired
  max length 120
- postal_codestring
  max length 20
- province_codestring
  max length 10
- country_codestringrequired
  ISO 3166-1 alpha-2 (IT; lowercase is accepted).
  
  min length 2max length 2
- phonestring
  max length 40
shippingobject
Child attributes
- method_codestring
  The shipping method, as configured in the merchant's carrier rules.
  
  max length 120
- method_namestring
  max length 255
- pricestring | number
  Shipping price in EUR, tax included. Default 0.
  
  min 0max 100000
- tax_ratenumber
  Tax percentage of the shipping, for example 22. Required with price.
  
  min 0max 100
notesstring
A note for the merchant and the warehouse; it is not returned by the API.

max length 2000
linesarray of objectrequired
min items 1max items 250
Attributes of each item
- skustring
  max length 255
- barcodestring
  max length 255
- titlestring
  Default the item's title in Nucleo.
  
  max length 255
- quantityintegerrequired
  min 1max 100000
- unit_pricestring | numberrequired
  Price of one piece in EUR, tax included, after discounts.
  
  min 0max 1000000
- tax_ratenumberrequired
  Tax percentage, for example 22.
  
  min 0max 100

Responses

200An order with this channel_order_ref already exists for your key; it is returned unchanged.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- idstring (uuid)required
- numberstringrequired
  Example: #1042
- statusstringrequired
  One ofreceivedon_holdin_fulfillmentshippeddeliveredcancellation_requestedcancelled
- channelstring | null
  Where the order comes from, for example shopify; nucleo_api for orders created with POST /orders.
- placed_atstring (date-time) | null
- updated_atstring (date-time) | null
- payment_statusstring | null
  One ofpendingauthorizedpaidcapturedpartially_refundedrefundedvoidedexpirednull
- on_holdboolean
- customerobject
  Child attributes
  namestring | null
  emailstring | null
  phonestring | null
- shipping_addressAddress
  Child attributes
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
- billing_addressAddress | null
  Address
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
- shippingobject
  The shipping method the customer chose.
  Child attributes
  method_codestring | null
  method_namestring | null
- currencystring
- totalsobject
  current_total is the total after edits and cancellations; refunded what was refunded on the sales channel.
  Child attributes
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  discountsMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  taxMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  current_totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  refundedMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- linesarray of OrderLinerequired
  Attributes of each item
  line_idstring
  skustring | null
  barcodestring | null
  titlestring | null
  quantityinteger
  quantity_cancelledinteger
  quantity_shippedinteger
  unit_priceMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  tax_ratestring
  Percentage as a decimal string, for example 22.00.
- shipmentsarray of Shipment
  Attributes of each item
  idstring
  statusstring
  One oflabel_createdconfirmedshippeddeliveredvoided
  location_codestring | null
  The location that shipped it.
  
  carrierobject
  Child attributes
  codestring | null
  namestring | null
  servicestring | null
  tracking_urlstring | null
  tracking_numbersarray of string
  shipped_atstring (date-time) | null
  delivered_atstring (date-time) | null
  linesarray of object
  Attributes of each item
  line_idstring | null
  quantityinteger
- refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- returnsarray of object
  The returns opened on the order; read each one with GET /returns/{return}.
  Attributes of each item
  idstring
  numberstring | null
  statusstring
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
- cancellationobject | null
  Present when the order is cancelled or its cancellation is requested.
  object
  reasonstring | null
  cancelled_atstring (date-time) | null
201The order was created.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- idstring (uuid)required
- numberstringrequired
  Example: #1042
- statusstringrequired
  One ofreceivedon_holdin_fulfillmentshippeddeliveredcancellation_requestedcancelled
- channelstring | null
  Where the order comes from, for example shopify; nucleo_api for orders created with POST /orders.
- placed_atstring (date-time) | null
- updated_atstring (date-time) | null
- payment_statusstring | null
  One ofpendingauthorizedpaidcapturedpartially_refundedrefundedvoidedexpirednull
- on_holdboolean
- customerobject
  Child attributes
  namestring | null
  emailstring | null
  phonestring | null
- shipping_addressAddress
  Child attributes
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
- billing_addressAddress | null
  Address
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
- shippingobject
  The shipping method the customer chose.
  Child attributes
  method_codestring | null
  method_namestring | null
- currencystring
- totalsobject
  current_total is the total after edits and cancellations; refunded what was refunded on the sales channel.
  Child attributes
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  discountsMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  taxMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  current_totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  refundedMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- linesarray of OrderLinerequired
  Attributes of each item
  line_idstring
  skustring | null
  barcodestring | null
  titlestring | null
  quantityinteger
  quantity_cancelledinteger
  quantity_shippedinteger
  unit_priceMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  tax_ratestring
  Percentage as a decimal string, for example 22.00.
- shipmentsarray of Shipment
  Attributes of each item
  idstring
  statusstring
  One oflabel_createdconfirmedshippeddeliveredvoided
  location_codestring | null
  The location that shipped it.
  
  carrierobject
  Child attributes
  codestring | null
  namestring | null
  servicestring | null
  tracking_urlstring | null
  tracking_numbersarray of string
  shipped_atstring (date-time) | null
  delivered_atstring (date-time) | null
  linesarray of object
  Attributes of each item
  line_idstring | null
  quantityinteger
- refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- returnsarray of object
  The returns opened on the order; read each one with GET /returns/{return}.
  Attributes of each item
  idstring
  numberstring | null
  statusstring
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
- cancellationobject | null
  Present when the order is cancelled or its cancellation is requested.
  object
  reasonstring | null
  cancelled_atstring (date-time) | null
400The request is not valid: validation_failed (with details per parameter or field), invalid_cursor, invalid_json (the body is not a JSON object) or unknown_item (with details per line, for example lines.0). 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.
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.
409number_taken (another order has this number), idempotency_key_reused or idempotency_key_in_progress (with 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.
413The body is larger than 5 MB (payload_too_large). Nothing was read.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 POST https://api-commerce.nucleoplatform.com/api/commerce/v1/orders \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "channel_order_ref": "SO-2026-00871",
  "number": "B2B-871",
  "placed_at": "2026-10-13T10:12:00+02:00",
  "customer": {
    "name": "Anna Rossi",
    "email": "buyer@example.com"
  },
  "shipping_address": {
    "first_name": "Anna",
    "last_name": "Rossi",
    "company": "Rossi Boutique",
    "address1": "Via Emilia 120",
    "city": "Modena",
    "postal_code": "41121",
    "province_code": "MO",
    "country_code": "IT",
    "phone": "+39 059 000000"
  },
  "shipping": {
    "method_code": "standard",
    "method_name": "Standard",
    "price": "5.00",
    "tax_rate": 22
  },
  "lines": [
    {
      "sku": "TEE-BLK-M",
      "quantity": 2,
      "unit_price": "29.90",
      "tax_rate": 22
    },
    {
      "barcode": "8000000000017",
      "quantity": 1,
      "unit_price": "59.00",
      "tax_rate": 22
    }
  ]
}'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/commerce/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "channel_order_ref": "SO-2026-00871",
    "number": "B2B-871",
    "placed_at": "2026-10-13T10:12:00+02:00",
    "customer": {
      "name": "Anna Rossi",
      "email": "buyer@example.com"
    },
    "shipping_address": {
      "first_name": "Anna",
      "last_name": "Rossi",
      "company": "Rossi Boutique",
      "address1": "Via Emilia 120",
      "city": "Modena",
      "postal_code": "41121",
      "province_code": "MO",
      "country_code": "IT",
      "phone": "+39 059 000000"
    },
    "shipping": {
      "method_code": "standard",
      "method_name": "Standard",
      "price": "5.00",
      "tax_rate": 22
    },
    "lines": [
      {
        "sku": "TEE-BLK-M",
        "quantity": 2,
        "unit_price": "29.90",
        "tax_rate": 22
      },
      {
        "barcode": "8000000000017",
        "quantity": 1,
        "unit_price": "59.00",
        "tax_rate": 22
      }
    ]
  }),
});
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-commerce.nucleoplatform.com/api/commerce/v1/orders', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
    ],
    'json' => [
        'channel_order_ref' => 'SO-2026-00871',
        'number' => 'B2B-871',
        'placed_at' => '2026-10-13T10:12:00+02:00',
        'customer' => [
            'name' => 'Anna Rossi',
            'email' => 'buyer@example.com',
        ],
        'shipping_address' => [
            'first_name' => 'Anna',
            'last_name' => 'Rossi',
            'company' => 'Rossi Boutique',
            'address1' => 'Via Emilia 120',
            'city' => 'Modena',
            'postal_code' => '41121',
            'province_code' => 'MO',
            'country_code' => 'IT',
            'phone' => '+39 059 000000',
        ],
        'shipping' => [
            'method_code' => 'standard',
            'method_name' => 'Standard',
            'price' => '5.00',
            'tax_rate' => 22,
        ],
        'lines' => [
            [
                'sku' => 'TEE-BLK-M',
                'quantity' => 2,
                'unit_price' => '29.90',
                'tax_rate' => 22,
            ],
            [
                'barcode' => '8000000000017',
                'quantity' => 1,
                'unit_price' => '59.00',
                'tax_rate' => 22,
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
  "number": "#1042",
  "status": "received",
  "channel": "string",
  "placed_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z",
  "payment_status": "pending",
  "on_hold": true,
  "customer": {
    "name": "string",
    "email": "string",
    "phone": "string"
  },
  "shipping_address": {
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postal_code": "string",
    "province_code": "string",
    "country_code": "string",
    "phone": "string"
  },
  "billing_address": {
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postal_code": "string",
    "province_code": "string",
    "country_code": "string",
    "phone": "string"
  },
  "shipping": {
    "method_code": "string",
    "method_name": "string"
  },
  "currency": "string",
  "totals": {
    "subtotal": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "discounts": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "shipping": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "tax": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "total": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "current_total": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "refunded": {
      "amount": "180.00",
      "currency": "EUR"
    }
  },
  "lines": [
    {
      "line_id": "string",
      "sku": "string",
      "barcode": "string",
      "title": "string",
      "quantity": 1,
      "quantity_cancelled": 1,
      "quantity_shipped": 1,
      "unit_price": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "tax_rate": "string"
    }
  ],
  "shipments": [
    {
      "id": "string",
      "status": "label_created",
      "location_code": "string",
      "carrier": {
        "code": "string",
        "name": "string",
        "service": "string"
      },
      "tracking_url": "string",
      "tracking_numbers": [
        "string"
      ],
      "shipped_at": "2026-10-01T09:30:00Z",
      "delivered_at": "2026-10-01T09:30:00Z",
      "lines": [
        {
          "line_id": "string",
          "quantity": 1
        }
      ]
    }
  ],
  "refunds": [
    {
      "id": "string",
      "return_id": "string",
      "refunded_at": "2026-10-01T09:30:00Z",
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "shipping": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "lines": [
        {
          "line_id": "string",
          "sku": "string",
          "barcode": "string",
          "quantity": 1,
          "subtotal": {
            "amount": "180.00",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "returns": [
    {
      "id": "string",
      "number": "string",
      "status": "requested"
    }
  ],
  "cancellation": {
    "reason": "string",
    "cancelled_at": "2026-10-01T09:30:00Z"
  }
}

{
  "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
  "number": "#1042",
  "status": "received",
  "channel": "string",
  "placed_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z",
  "payment_status": "pending",
  "on_hold": true,
  "customer": {
    "name": "string",
    "email": "string",
    "phone": "string"
  },
  "shipping_address": {
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postal_code": "string",
    "province_code": "string",
    "country_code": "string",
    "phone": "string"
  },
  "billing_address": {
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postal_code": "string",
    "province_code": "string",
    "country_code": "string",
    "phone": "string"
  },
  "shipping": {
    "method_code": "string",
    "method_name": "string"
  },
  "currency": "string",
  "totals": {
    "subtotal": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "discounts": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "shipping": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "tax": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "total": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "current_total": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "refunded": {
      "amount": "180.00",
      "currency": "EUR"
    }
  },
  "lines": [
    {
      "line_id": "string",
      "sku": "string",
      "barcode": "string",
      "title": "string",
      "quantity": 1,
      "quantity_cancelled": 1,
      "quantity_shipped": 1,
      "unit_price": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "tax_rate": "string"
    }
  ],
  "shipments": [
    {
      "id": "string",
      "status": "label_created",
      "location_code": "string",
      "carrier": {
        "code": "string",
        "name": "string",
        "service": "string"
      },
      "tracking_url": "string",
      "tracking_numbers": [
        "string"
      ],
      "shipped_at": "2026-10-01T09:30:00Z",
      "delivered_at": "2026-10-01T09:30:00Z",
      "lines": [
        {
          "line_id": "string",
          "quantity": 1
        }
      ]
    }
  ],
  "refunds": [
    {
      "id": "string",
      "return_id": "string",
      "refunded_at": "2026-10-01T09:30:00Z",
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "shipping": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "lines": [
        {
          "line_id": "string",
          "sku": "string",
          "barcode": "string",
          "quantity": 1,
          "subtotal": {
            "amount": "180.00",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "returns": [
    {
      "id": "string",
      "number": "string",
      "status": "requested"
    }
  ],
  "cancellation": {
    "reason": "string",
    "cancelled_at": "2026-10-01T09:30:00Z"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c",
    "details": {
      "status": [
        "Must be one of: received, on_hold, in_fulfillment, shipped, delivered, cancellation_requested, cancelled."
      ]
    }
  }
}

{
  "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": "number_taken",
    "message": "Another order is already numbered API-B2B-871: send a different number.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

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

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

get/orders/{order}

Get an order

One order, by number or id. Scope orders:read.

GET https://api-commerce.nucleoplatform.com/api/commerce/v1/orders/{order}

Authentication: Bearer token

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

Path parameters

orderstringrequired
The order number (1042, %231042) or the order id.

Example: 1042

Responses

200The order.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- idstring (uuid)required
- numberstringrequired
  Example: #1042
- statusstringrequired
  One ofreceivedon_holdin_fulfillmentshippeddeliveredcancellation_requestedcancelled
- channelstring | null
  Where the order comes from, for example shopify; nucleo_api for orders created with POST /orders.
- placed_atstring (date-time) | null
- updated_atstring (date-time) | null
- payment_statusstring | null
  One ofpendingauthorizedpaidcapturedpartially_refundedrefundedvoidedexpirednull
- on_holdboolean
- customerobject
  Child attributes
  namestring | null
  emailstring | null
  phonestring | null
- shipping_addressAddress
  Child attributes
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
- billing_addressAddress | null
  Address
  first_namestring | null
  last_namestring | null
  companystring | null
  address1string | null
  address2string | null
  citystring | null
  postal_codestring | null
  province_codestring | null
  country_codestring | null
  ISO 3166-1 alpha-2.
  
  phonestring | null
- shippingobject
  The shipping method the customer chose.
  Child attributes
  method_codestring | null
  method_namestring | null
- currencystring
- totalsobject
  current_total is the total after edits and cancellations; refunded what was refunded on the sales channel.
  Child attributes
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  discountsMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  taxMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  current_totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  refundedMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- linesarray of OrderLinerequired
  Attributes of each item
  line_idstring
  skustring | null
  barcodestring | null
  titlestring | null
  quantityinteger
  quantity_cancelledinteger
  quantity_shippedinteger
  unit_priceMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  totalMoney
  Tax included.
  
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  tax_ratestring
  Percentage as a decimal string, for example 22.00.
- shipmentsarray of Shipment
  Attributes of each item
  idstring
  statusstring
  One oflabel_createdconfirmedshippeddeliveredvoided
  location_codestring | null
  The location that shipped it.
  
  carrierobject
  Child attributes
  codestring | null
  namestring | null
  servicestring | null
  tracking_urlstring | null
  tracking_numbersarray of string
  shipped_atstring (date-time) | null
  delivered_atstring (date-time) | null
  linesarray of object
  Attributes of each item
  line_idstring | null
  quantityinteger
- refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- returnsarray of object
  The returns opened on the order; read each one with GET /returns/{return}.
  Attributes of each item
  idstring
  numberstring | null
  statusstring
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
- cancellationobject | null
  Present when the order is cancelled or its cancellation is requested.
  object
  reasonstring | null
  cancelled_atstring (date-time) | null
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.
404order_not_found or return_not_found.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/orders/1042 \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

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

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

Response

{
  "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
  "number": "#1042",
  "status": "received",
  "channel": "string",
  "placed_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z",
  "payment_status": "pending",
  "on_hold": true,
  "customer": {
    "name": "string",
    "email": "string",
    "phone": "string"
  },
  "shipping_address": {
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postal_code": "string",
    "province_code": "string",
    "country_code": "string",
    "phone": "string"
  },
  "billing_address": {
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postal_code": "string",
    "province_code": "string",
    "country_code": "string",
    "phone": "string"
  },
  "shipping": {
    "method_code": "string",
    "method_name": "string"
  },
  "currency": "string",
  "totals": {
    "subtotal": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "discounts": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "shipping": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "tax": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "total": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "current_total": {
      "amount": "180.00",
      "currency": "EUR"
    },
    "refunded": {
      "amount": "180.00",
      "currency": "EUR"
    }
  },
  "lines": [
    {
      "line_id": "string",
      "sku": "string",
      "barcode": "string",
      "title": "string",
      "quantity": 1,
      "quantity_cancelled": 1,
      "quantity_shipped": 1,
      "unit_price": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "tax_rate": "string"
    }
  ],
  "shipments": [
    {
      "id": "string",
      "status": "label_created",
      "location_code": "string",
      "carrier": {
        "code": "string",
        "name": "string",
        "service": "string"
      },
      "tracking_url": "string",
      "tracking_numbers": [
        "string"
      ],
      "shipped_at": "2026-10-01T09:30:00Z",
      "delivered_at": "2026-10-01T09:30:00Z",
      "lines": [
        {
          "line_id": "string",
          "quantity": 1
        }
      ]
    }
  ],
  "refunds": [
    {
      "id": "string",
      "return_id": "string",
      "refunded_at": "2026-10-01T09:30:00Z",
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "shipping": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "lines": [
        {
          "line_id": "string",
          "sku": "string",
          "barcode": "string",
          "quantity": 1,
          "subtotal": {
            "amount": "180.00",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "returns": [
    {
      "id": "string",
      "number": "string",
      "status": "requested"
    }
  ],
  "cancellation": {
    "reason": "string",
    "cancelled_at": "2026-10-01T09: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": "order_not_found",
    "message": "Order 1042 not found.",
    "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"
  }
}

get/orders/{order}/timeline

Get an order's timeline

What happened to the order, oldest first: status changes, holds, address and line changes, shipments, returns and refunds. Internal events (routing, notes, customer care) are not listed. Scope orders:read.

GET https://api-commerce.nucleoplatform.com/api/commerce/v1/orders/{order}/timeline

Authentication: Bearer token

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

Path parameters

orderstringrequired
The order number (1042, %231042) or the order id.

Example: 1042

Responses

200The order's public events.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- dataarray of TimelineEventrequired
  Attributes of each item
  typestring
  One oforder.receivedorder.status_changedorder.hold_placedorder.hold_releasedorder.address_changedorder.shipping_method_changedorder.lines_changedorder.lines_cancelledorder.item_replacedorder.reship_createdorder.refunded_on_channelshipment.confirmedshipment.shippedshipment.tracking_updatedshipment.voidedreturn.requestedreturn.status_changedstore.ready_for_pickupstore.collected
  from_statusstring | null
  For status changes, the public status before (an order status, or a return status for return.status_changed).
  
  to_statusstring | null
  occurred_atstring (date-time) | null
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.
404order_not_found or return_not_found.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/orders/1042/timeline \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

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

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

Response

{
  "data": [
    {
      "type": "order.received",
      "from_status": null,
      "to_status": null,
      "occurred_at": "2026-10-12T09:14:00Z"
    },
    {
      "type": "order.status_changed",
      "from_status": "received",
      "to_status": "in_fulfillment",
      "occurred_at": "2026-10-12T09:15:02Z"
    },
    {
      "type": "shipment.shipped",
      "from_status": null,
      "to_status": null,
      "occurred_at": "2026-10-12T16:40:11Z"
    }
  ]
}

{
  "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": "order_not_found",
    "message": "Order 1042 not found.",
    "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"
  }
}

Returns

Returns come from the sales channel, where the customer opens them. Nucleo follows them to the warehouse and records what arrived and in which condition.

Status	Meaning
`requested`	Opened on the sales channel.
`awaiting_receipt`	The warehouse knows it is coming.
`in_transit`	The parcel is travelling back.
`received`	Arrived at the warehouse, being checked.
`compliant`	Every item arrived, in sellable condition.
`not_compliant`	Something is missing or not sellable: the merchant's customer service is alerted.
`closed`	Done.
`cancelled`	Cancelled.

get/returns

List returns

Returns sorted by last update, oldest first. Scope returns:read.

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

Authentication: Bearer token

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

Query parameters

statusstring
Only returns in this status.

One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
Example: requested
updated_sincestring (date-time)
Only items updated at or after this time (ISO 8601). Encode + as %2B if you send an offset.

Example: 2026-10-13T08:00:00Z
cursorstring
The next_cursor of the previous page. Keep status and updated_since the same; a different status answers 400 invalid_cursor.
limitinteger
Items per page.

min 1max 200default 50
Example: 50

Responses

200A page of returns.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- dataarray of Returnrequired
  Attributes of each item
  idstringrequired
  numberstring | null
  order_idstring | null
  order_numberstring | null
  statusstringrequired
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
  reason_codestring | null
  reason_textstring | null
  customer_notestring | null
  currencystring
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  created_atstring (date-time) | null
  updated_atstring (date-time) | null
  received_atstring (date-time) | null
  closed_atstring (date-time) | null
  cancelled_atstring (date-time) | null
  linesarray of objectrequired
  Attributes of each item
  skustring | null
  barcodestring | null
  titlestring | null
  quantity_requestedinteger
  quantity_receivedinteger
  reason_codestring | null
  outcomestring | null
  The condition the warehouse found — sellable, damaged, or mixed when the pieces differ; null until checked.
  
  refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- next_cursorstring | nullrequired
400The request is not valid: validation_failed (with details per parameter or field), invalid_cursor, invalid_json (the body is not a JSON object) or unknown_item (with details per line, for example lines.0). 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.
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/returns?status=requested&updated_since=2026-10-13T08%3A00%3A00Z&limit=50' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/commerce/v1/returns?status=requested&updated_since=2026-10-13T08%3A00%3A00Z&limit=50", {
  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/returns?status=requested&updated_since=2026-10-13T08%3A00%3A00Z&limit=50', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

Response

{
  "data": [
    {
      "id": "string",
      "number": "string",
      "order_id": "string",
      "order_number": "string",
      "status": "requested",
      "reason_code": "string",
      "reason_text": "string",
      "customer_note": "string",
      "currency": "string",
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z",
      "received_at": "2026-10-01T09:30:00Z",
      "closed_at": "2026-10-01T09:30:00Z",
      "cancelled_at": "2026-10-01T09:30:00Z",
      "lines": [
        {
          "sku": "string",
          "barcode": "string",
          "title": "string",
          "quantity_requested": 1,
          "quantity_received": 1,
          "reason_code": "string",
          "outcome": "string"
        }
      ],
      "refunds": [
        {
          "id": "string",
          "return_id": "string",
          "refunded_at": "2026-10-01T09:30:00Z",
          "total": {
            "amount": "180.00",
            "currency": "EUR"
          },
          "shipping": {
            "amount": "180.00",
            "currency": "EUR"
          },
          "lines": [
            {}
          ]
        }
      ]
    }
  ],
  "next_cursor": "string"
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c",
    "details": {
      "status": [
        "Must be one of: received, on_hold, in_fulfillment, shipped, delivered, cancellation_requested, cancelled."
      ]
    }
  }
}

{
  "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"
  }
}

get/returns/{return}

Get a return

One return, by number or id. Scope returns:read.

GET https://api-commerce.nucleoplatform.com/api/commerce/v1/returns/{return}

Authentication: Bearer token

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

Path parameters

returnstringrequired
The return's number (as shown in Nucleo) or its id.

Example: R-1042-1

Responses

200The return.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- idstringrequired
- numberstring | null
- order_idstring | null
- order_numberstring | null
- statusstringrequired
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
- reason_codestring | null
- reason_textstring | null
- customer_notestring | null
- currencystring
- totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- created_atstring (date-time) | null
- updated_atstring (date-time) | null
- received_atstring (date-time) | null
- closed_atstring (date-time) | null
- cancelled_atstring (date-time) | null
- linesarray of objectrequired
  Attributes of each item
  skustring | null
  barcodestring | null
  titlestring | null
  quantity_requestedinteger
  quantity_receivedinteger
  reason_codestring | null
  outcomestring | null
  The condition the warehouse found — sellable, damaged, or mixed when the pieces differ; null until checked.
- refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
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.
404order_not_found or return_not_found.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/returns/R-1042-1 \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

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

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

Response

{
  "id": "string",
  "number": "string",
  "order_id": "string",
  "order_number": "string",
  "status": "requested",
  "reason_code": "string",
  "reason_text": "string",
  "customer_note": "string",
  "currency": "string",
  "total": {
    "amount": "180.00",
    "currency": "EUR"
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z",
  "received_at": "2026-10-01T09:30:00Z",
  "closed_at": "2026-10-01T09:30:00Z",
  "cancelled_at": "2026-10-01T09:30:00Z",
  "lines": [
    {
      "sku": "string",
      "barcode": "string",
      "title": "string",
      "quantity_requested": 1,
      "quantity_received": 1,
      "reason_code": "string",
      "outcome": "string"
    }
  ],
  "refunds": [
    {
      "id": "string",
      "return_id": "string",
      "refunded_at": "2026-10-01T09:30:00Z",
      "total": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "shipping": {
        "amount": "180.00",
        "currency": "EUR"
      },
      "lines": [
        {
          "line_id": "string",
          "sku": "string",
          "barcode": "string",
          "quantity": 1,
          "subtotal": {
            "amount": "180.00",
            "currency": "EUR"
          }
        }
      ]
    }
  ]
}

{
  "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": "order_not_found",
    "message": "Order 1042 not found.",
    "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"
  }
}

Inventory

What you can sell now, per item and location: stock on hand, minus what is reserved for open orders and the safety stock, never below zero. With channel, the sales channel's allocation rules apply too: only the locations it sells from, minus the pieces held for other channels, within its caps. Pre-order quantities are not included.

get/inventory

Get availability

Availability for up to 100 items per call, by SKU or barcode (or both). Only locations with stock or reservations for the item are listed; an SKU or barcode Nucleo does not know is left out of the answer. With channel, that sales channel's allocation rules apply. Scope inventory:read.

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

Authentication: Bearer token

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

Query parameters

skustring
Comma-separated SKUs.

Example: TEE-BLK-M,TEE-BLK-L
barcodestring
Comma-separated barcodes (EAN/UPC).

Example: 8056377587370
channelstring
A sales channel type (for example shopify) or the id of a sales channel connection.

Responses

200Availability per item.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- channelstring | nullrequired
- dataarray of objectrequired
  Attributes of each item
  skustring | null
  barcodestring
  availableinteger
  Sum of available over the listed locations.
  
  incominginteger
  Pieces on inbound shipments expected in the next 365 days, not yet received.
  
  locationsarray of object
  Attributes of each item
  location_codestring | null
  on_handinteger
  reservedinteger
  Held for open orders.
  
  availableinteger
400The request is not valid: validation_failed (with details per parameter or field), invalid_cursor, invalid_json (the body is not a JSON object) or unknown_item (with details per line, for example lines.0). 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.
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/inventory?sku=TEE-BLK-M%2CTEE-BLK-L&barcode=8056377587370' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/commerce/v1/inventory?sku=TEE-BLK-M%2CTEE-BLK-L&barcode=8056377587370", {
  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/inventory?sku=TEE-BLK-M%2CTEE-BLK-L&barcode=8056377587370', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

Response

{
  "channel": null,
  "data": [
    {
      "sku": "TEE-BLK-M",
      "barcode": "8056377587370",
      "available": 5,
      "incoming": 0,
      "locations": [
        {
          "location_code": "WH1",
          "on_hand": 6,
          "reserved": 1,
          "available": 5
        }
      ]
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c",
    "details": {
      "status": [
        "Must be one of: received, on_hold, in_fulfillment, shipped, delivered, cancellation_requested, cancelled."
      ]
    }
  }
}

{
  "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"
  }
}

Locations

Warehouses and stores of the company, with the codes used in shipments and availability.

get/locations

List locations

Every warehouse and store of the company, by code. Scope locations:read.

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

Authentication: Bearer token

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

Responses

200The locations.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- dataarray of Locationrequired
  Attributes of each item
  codestring
  namestring
  kindstring
  One ofwarehousestoremarketplace
  fulfills_onlineboolean
  Whether it ships online orders.
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/locations \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

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

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

Response

{
  "data": [
    {
      "code": "MI01",
      "name": "Milan flagship",
      "kind": "store",
      "fulfills_online": true
    },
    {
      "code": "WH1",
      "name": "Main warehouse",
      "kind": "warehouse",
      "fulfills_online": true
    }
  ]
}

{
  "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"
  }
}

Webhooks

Nucleo can call your server when something changes. In the connection's Settings, write your Webhook URL (https only, on a public address) and save. Your key receives the events of its scopes:

Event	Scope	When
`order.created`	`orders:read`	A new order arrives from the sales channel or through `POST /orders`, or the merchant creates a replacement order.
`order.status_changed`	`orders:read`	The order's public status changes (internal steps that keep the same public status send nothing).
`shipment.shipped`	`orders:read`	A shipment leaves: one event per shipment, also when an order ships in several parcels.
`return.created`	`returns:read`	A return is opened, or the warehouse receives one nobody announced.
`return.status_changed`	`returns:read`	The return's public status changes.

Webhooks are hints, not data: read the order or the return with the API to get its current state. Events can arrive out of order and, after a retry, more than once: skip an id you already handled. Keep your periodic sync with updated_since as a safety net. GET /ping tells whether webhooks are on and which events your key receives.

Webhookorder.created

A new order arrived

Sent when an order arrives from the sales channel or through POST /orders (also to the key that created it), or when the merchant creates a replacement order (for example to resend lost goods). Needs orders:read.

Request Nucleo sendsapplication/json

idstring (uuid)required
Unique per event and the same on every retry. Skip an id you already handled.
typestringrequired
One oforder.createdorder.status_changedshipment.shippedreturn.createdreturn.status_changed
created_atstring (date-time)required
When the change happened in Nucleo.
dataobjectrequired
Orders and shipments: order_id, order_number; order.created and order.status_changed add status (an order status), order.status_changed also previous_status; shipment.shipped adds shipment_id. Returns: return_id, return_number, order_id, order_number and status (a return status); return.status_changed also previous_status.

Expected response

200Answer with any 2xx within 10 seconds; the body is ignored. Any other answer, a redirect or a timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt carries the same id (also in X-Nucleo-Webhook-Id) and its number in X-Nucleo-Attempt. While the connection is paused or still a draft no webhook is sent, and the events of that time are not sent later: catch up with updated_since.

Body

{
  "id": "5b7e1c2d-3a4f-4b6c-8d9e-0f1a2b3c4d5e",
  "type": "order.created",
  "created_at": "2026-10-13T08:29:51Z",
  "data": {
    "order_id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "order_number": "#1042",
    "status": "received"
  }
}

Response

HTTP 200 — Answer with any `2xx` within 10 seconds; the body is ignored. Any other answer, a redirect or a
timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32
minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt
carries the same `id` (also in `X-Nucleo-Webhook-Id`) and its number in `X-Nucleo-Attempt`.
While the connection is paused or still a draft no webhook is sent, and the events of that time are
not sent later: catch up with `updated_since`.

Webhookorder.status_changed

An order changed status

Sent when the order's public status changes, with the new status and the previous_status. Needs orders:read.

Request Nucleo sendsapplication/json

idstring (uuid)required
Unique per event and the same on every retry. Skip an id you already handled.
typestringrequired
One oforder.createdorder.status_changedshipment.shippedreturn.createdreturn.status_changed
created_atstring (date-time)required
When the change happened in Nucleo.
dataobjectrequired
Orders and shipments: order_id, order_number; order.created and order.status_changed add status (an order status), order.status_changed also previous_status; shipment.shipped adds shipment_id. Returns: return_id, return_number, order_id, order_number and status (a return status); return.status_changed also previous_status.

Expected response

200Answer with any 2xx within 10 seconds; the body is ignored. Any other answer, a redirect or a timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt carries the same id (also in X-Nucleo-Webhook-Id) and its number in X-Nucleo-Attempt. While the connection is paused or still a draft no webhook is sent, and the events of that time are not sent later: catch up with updated_since.

Body

{
  "id": "8c9d0e1f-2a3b-4c4d-9e5f-6a7b8c9d0e1f",
  "type": "order.status_changed",
  "created_at": "2026-10-13T16:02:14Z",
  "data": {
    "order_id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "order_number": "#1042",
    "status": "shipped",
    "previous_status": "in_fulfillment"
  }
}

Response

HTTP 200 — Answer with any `2xx` within 10 seconds; the body is ignored. Any other answer, a redirect or a
timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32
minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt
carries the same `id` (also in `X-Nucleo-Webhook-Id`) and its number in `X-Nucleo-Attempt`.
While the connection is paused or still a draft no webhook is sent, and the events of that time are
not sent later: catch up with `updated_since`.

Webhookshipment.shipped

A shipment left

Sent for each shipment that leaves, also when the order ships in several parcels from different locations. shipment_id is the id of one of the order's shipments, with carrier and tracking. An order the customer collects in a store sends no shipment.shipped: it goes straight to delivered. Needs orders:read.

Request Nucleo sendsapplication/json

idstring (uuid)required
Unique per event and the same on every retry. Skip an id you already handled.
typestringrequired
One oforder.createdorder.status_changedshipment.shippedreturn.createdreturn.status_changed
created_atstring (date-time)required
When the change happened in Nucleo.
dataobjectrequired
Orders and shipments: order_id, order_number; order.created and order.status_changed add status (an order status), order.status_changed also previous_status; shipment.shipped adds shipment_id. Returns: return_id, return_number, order_id, order_number and status (a return status); return.status_changed also previous_status.

Expected response

200Answer with any 2xx within 10 seconds; the body is ignored. Any other answer, a redirect or a timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt carries the same id (also in X-Nucleo-Webhook-Id) and its number in X-Nucleo-Attempt. While the connection is paused or still a draft no webhook is sent, and the events of that time are not sent later: catch up with updated_since.

Body

{
  "id": "1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "type": "shipment.shipped",
  "created_at": "2026-10-13T16:02:15Z",
  "data": {
    "order_id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "order_number": "#1042",
    "shipment_id": "7c6b5a4f-3e2d-4c1b-9a0f-8e7d6c5b4a3f"
  }
}

Response

HTTP 200 — Answer with any `2xx` within 10 seconds; the body is ignored. Any other answer, a redirect or a
timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32
minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt
carries the same `id` (also in `X-Nucleo-Webhook-Id`) and its number in `X-Nucleo-Attempt`.
While the connection is paused or still a draft no webhook is sent, and the events of that time are
not sent later: catch up with `updated_since`.

Webhookreturn.created

A return was opened

Sent when a return is opened on the sales channel, or when the warehouse receives a return nobody announced. Needs returns:read.

Request Nucleo sendsapplication/json

idstring (uuid)required
Unique per event and the same on every retry. Skip an id you already handled.
typestringrequired
One oforder.createdorder.status_changedshipment.shippedreturn.createdreturn.status_changed
created_atstring (date-time)required
When the change happened in Nucleo.
dataobjectrequired
Orders and shipments: order_id, order_number; order.created and order.status_changed add status (an order status), order.status_changed also previous_status; shipment.shipped adds shipment_id. Returns: return_id, return_number, order_id, order_number and status (a return status); return.status_changed also previous_status.

Expected response

200Answer with any 2xx within 10 seconds; the body is ignored. Any other answer, a redirect or a timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt carries the same id (also in X-Nucleo-Webhook-Id) and its number in X-Nucleo-Attempt. While the connection is paused or still a draft no webhook is sent, and the events of that time are not sent later: catch up with updated_since.

Body

{
  "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "type": "return.created",
  "created_at": "2026-10-18T16:20:03Z",
  "data": {
    "return_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "return_number": "R1042-1",
    "order_id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "order_number": "#1042",
    "status": "requested"
  }
}

Response

HTTP 200 — Answer with any `2xx` within 10 seconds; the body is ignored. Any other answer, a redirect or a
timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32
minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt
carries the same `id` (also in `X-Nucleo-Webhook-Id`) and its number in `X-Nucleo-Attempt`.
While the connection is paused or still a draft no webhook is sent, and the events of that time are
not sent later: catch up with `updated_since`.

Webhookreturn.status_changed

A return changed status

Sent when the return's public status changes, with the new status and the previous_status. Needs returns:read.

Request Nucleo sendsapplication/json

idstring (uuid)required
Unique per event and the same on every retry. Skip an id you already handled.
typestringrequired
One oforder.createdorder.status_changedshipment.shippedreturn.createdreturn.status_changed
created_atstring (date-time)required
When the change happened in Nucleo.
dataobjectrequired
Orders and shipments: order_id, order_number; order.created and order.status_changed add status (an order status), order.status_changed also previous_status; shipment.shipped adds shipment_id. Returns: return_id, return_number, order_id, order_number and status (a return status); return.status_changed also previous_status.

Expected response

200Answer with any 2xx within 10 seconds; the body is ignored. Any other answer, a redirect or a timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt carries the same id (also in X-Nucleo-Webhook-Id) and its number in X-Nucleo-Attempt. While the connection is paused or still a draft no webhook is sent, and the events of that time are not sent later: catch up with updated_since.

Body

{
  "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "return.status_changed",
  "created_at": "2026-10-21T09:41:27Z",
  "data": {
    "return_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "return_number": "R1042-1",
    "order_id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
    "order_number": "#1042",
    "status": "compliant",
    "previous_status": "received"
  }
}

Response

HTTP 200 — Answer with any `2xx` within 10 seconds; the body is ignored. Any other answer, a redirect or a
timeout is retried with exponential backoff (after about 30 seconds, then 1, 2, 4, 8, 16 and 32
minutes): 8 attempts in about an hour, then Nucleo gives up and alerts the merchant. Every attempt
carries the same `id` (also in `X-Nucleo-Webhook-Id`) and its number in `X-Nucleo-Attempt`.
While the connection is paused or still a draft no webhook is sent, and the events of that time are
not sent later: catch up with `updated_since`.