/

Contents

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.

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

Endpoints

get/ordersList orders
post/ordersCreate an order
get/orders/{order}Get an order
get/orders/{order}/timelineGet an order's timeline

get/orders

List orders

Requires the orders:read scope.

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

Requires the orders:write scope.

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

Requires the orders:read scope.

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

Requires the orders:read scope.

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

Was this page helpful?