/ Developers
Contents
CommerceBetaVersion v1

WMS T-Data API

T-Data compatible /V1 facade that a warehouse management system polls to fulfil Nucleo Commerce orders and returns.

The WMS T-Data facade lets a warehouse or 3PL management system (WMS) fulfil the orders of a Nucleo Commerce merchant using the T-Data "Integration MoR/WMS" /V1 contract: same paths, same methods, same JSON fields. A WMS that already speaks T-Data only changes the base URL and the credentials.

The warehouse is always the caller. Nucleo never calls the WMS: the WMS polls for new orders and expected returns and pushes acknowledgements, picking results, shipments, stock levels and return outcomes.

Authentication. Every call carries the credentials of one warehouse connection: an API key in X-Api-Key (recommended), the same key as Authorization: Bearer <key>, or HTTP Basic. The credentials alone identify the merchant and the warehouse; there is no store identifier in the path.

Integration flow

  1. Download orders – GET /V1/Orders/New every 1–5 minutes. An order is returned at every call until you acknowledge it.
  2. Acknowledge – POST /V1/Orders/Acknowledge with Success: true (taken over) or Success: false plus a rejection code.
  3. Picking result – POST /V1/Orders/Processed with picked quantities and parcels (full or partial pick).
  4. Shipment – POST /V1/Orders/Shipped with courier and waybill. Nucleo creates the fulfilment on the sales channel and the customer receives the tracking.
  5. Cannot fulfil – POST /V1/Orders/Canceled when an acknowledged order cannot be shipped.
  6. Stock – PUT /V1/Stock/Update with absolute levels, full or only the changed items, as often as stock changes.
  7. Returns – GET /V1/Returns/New → POST /V1/Returns/Acknowledge → POST /V1/Return/Update with the per-line outcome after inspection; POST /V1/Returns/Canceled for an expected return that will not arrive.
  8. Optional services – courier labels produced by Nucleo (/V1/Labels/*), order documents (/V1/Documents/Get) and the WMS item registry (/V1/Catalogue) are switched off by default and answer 404 until the merchant enables them.

Conventions

  • Paths are case-insensitive: /V1/Orders/New, /v1/orders/new and /V1/ORDERS/NEW are the same endpoint. Aliases: /V1/Orders/Cancel = /V1/Orders/Canceled, /V1/Returns/Update = /V1/Return/Update.
  • JSON in, JSON out (UTF-8). The request body is parsed as JSON whatever the Content-Type; send application/json.
  • Tolerant input, as in the T-Data samples: field names are case-insensitive; ErrorcCode and ErrorCode are equivalent; booleans are accepted as true/false, "True"/"False", 1/0; a trailing comma before } or ] is accepted; ProductList may be an array or an object wrapping the array.
  • Dates: Nucleo sends ISO 8601 UTC with Z (2026-10-05T08:12:30Z). It accepts ISO 8601 with offset and optional milliseconds (2026-10-05T16:54:40.408+02:00). A date without offset is read as UTC: always send the offset.
  • Order and return numbers: OmsOrderNumber is the channel order name exactly as the merchant sees it, including a leading # (#1042); encode it as %23 in query strings. OmsReturnNumber is the Nucleo return name.
  • Item key: Sku is the item code agreed for the connection, by default the variant barcode (EAN), both ways.
  • No pagination: Orders/New and Returns/New return at most 500 items per call, oldest first. The rest arrive on the next calls once you acknowledge what you received.
  • Validation is all-or-nothing: in calls carrying several items (an Acknowledge array, a Stock/Update list) a single invalid item rejects the whole call and nothing is applied.
  • Retries are safe: every write can be repeated after a timeout without double effects (see each operation).

Responses and errors

HTTPBodyWhen
200{"Success":true,"ErrorMessage":""}write accepted
200{"ErrorCode":"LabelNotReady","success":false}business error (labels and documents only)
400{"ErrorCode":"Exception","Message":"<reason>"}invalid JSON, missing field, unknown order or return
401{"ErrorCode":"Exception","Message":"Unauthorized"}missing or wrong credentials
403{"ErrorCode":"Exception","Message":"Forbidden"}caller IP not in the connection allowlist
404{"ErrorCode":"Exception","Message":"Not found"}unknown path, or optional service switched off
405{"ErrorCode":"Exception","Message":"Method not allowed"}wrong method for a known path
429{"ErrorCode":"Exception","Message":"Too many requests"}rate limit exceeded
500{"ErrorCode":"Exception","Message":"service paused"}connection paused by the merchant (service not active while still a draft): nothing read or written, retry later
500{"ErrorCode":"Exception","Message":"Internal error (ref <uuid>)"}unexpected error; quote the ref to support

Credentials must be sent on every request without waiting for a challenge: a 401 carries no WWW-Authenticate header.

Limits and monitoring

  • 600 calls per minute per connection (all endpoints together; the merchant can change it). No Retry-After or X-RateLimit-* headers are sent: on 429 back off for at least 60 seconds.
  • 30 failed authentications within 5 minutes from one IP block that IP for the rest of the window, valid credentials included.
  • Every call is logged in full (request and response) before Nucleo answers, so support can find any call by time, path or order.
  • If the WMS stays silent for more than 30 minutes while orders are waiting, Nucleo flags the connection as Error and alerts the merchant; the next successful call clears it.

Credentials

The merchant creates a warehouse connection of type T-Data in Commerce › Orders › Channels and logistics. Nucleo shows the endpoint, username, password and API key once; the merchant shares them with you over a separate channel. Rotate credentials on the same page invalidates the old ones immediately. A new connection starts as a draft and answers service not active until the merchant activates it.

Authentication

  • apiKeyAPI key · header · X-Api-Key

    48-character API key of the warehouse connection (recommended). Issued once by the merchant in Commerce › Orders › Channels and logistics, together with the username and password.

  • bearerKeyHTTP bearer

    The same API key sent as Authorization: Bearer <key>.

  • basicAuthHTTP basic

    Username and password of the warehouse connection, sent preemptively on every call.

Base URL
https://{host}Production. Use the endpoint shown when the credentials were issued (without the trailing `/V1`).
Who calls it
Warehouses
Endpoints
17
OpenAPI 3.1 specification
wms-tdata.yaml
{host} — Commerce API host. If the merchant sets a dedicated host on the connection, the connection answers only on that host; paths do not change. (examples use api-commerce.nucleoplatform.com; full URL https://api-commerce.nucleoplatform.com)

Orders

Download orders, acknowledge them, report picking, shipment or impossibility to fulfil.

get/V1/Orders/New

List orders to fulfil

Returns the orders allocated to this warehouse that are paid, free of holds and not yet acknowledged (positively or negatively) by this connection. No parameters.

  • An order is returned at every call until Orders/Acknowledge arrives: if a response is lost, the order comes back.
  • ProductList contains only the lines allocated to this warehouse, with the quantity still open. For an order split across warehouses you see only your part.
  • An order cancelled on the sales channel before you acknowledge it disappears from the list.
  • At most 500 orders per call, oldest order date first.
  • An order never reaches the warehouse while it is on hold (payment pending, hold tag, fraud risk, manual hold, no carrier rule for the destination, line without item key). When documents are enabled, an order that needs external documents is returned only once they are ready.
  • Side effect: the first time an order is returned it moves to Exported. Until it is acknowledged Nucleo keeps subtracting it from your stock before publishing availability (see Stock/Update).
  • With Nucleo-managed courier labels enabled, the return label (IdLabel 0) and the first parcel label (IdLabel 1) are generated when the order is first returned.

Note that the body carries "StatusCode": 201 while the HTTP status is 200, as in the T-Data contract.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/V1/Orders/New
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Responses

  • 200Orders waiting for acknowledgement (possibly none).
    • Contentarray of NewOrderrequired
      max items 500
      Attributes of each item
      • OrderDataobjectrequired
        Child attributes
        • OmsOrderNumberstring

          Channel order name; the key for every later call.

          Example: #1042
        • OmsCustomerIdstring | null

          Numeric part of the channel customer id; null for guest orders.

          Example: 7712345678
        • OrderDateTimestring (date-time)

          Order date, UTC.

          Example: 2026-10-05T08:12:30Z
        • HasExternalDocumentsstring

          String, as in the T-Data contract. Always "false" while documents are off.

          One oftruefalse
        • PreparationTypestring

          Preparation code from the merchant's order-tag mapping; default "001".

          Example: 001
        • OrderType"B2C"
        • SelectedCourierstring

          Carrier chosen by the merchant's carrier rules in Nucleo.

          Example: GLS
        • Priorityinteger

          Order priority: merchant-set, by destination country, or 1 for express and 3 for standard by default.

          Example: 3
        • UserLanguagestring

          Language from the shipping country (GB en-US, DE/AT de-DE, ES/PT es-ES, FR/CH/BE fr-FR, IT it-IT; others en-US unless the merchant changed it).

          Example: it-IT
        • ShipmentTypeinteger

          1 standard, 2 express.

          One of12
      • ShippingDataobjectrequired
        Child attributes
        • FirstNamestring
        • LastNamestring
        • EmailAddressstring (email)
        • PhoneNumberstring

          Shipping address phone, else the customer phone.

        • Addressobject
          Child attributes
          • Citystring
          • CountryCodestring

            ISO 3166-1 alpha-2.

            Example: IT
          • PostalCodestring
          • StateOrProvinceCodestring
          • Streetstring

            Address lines 1 and 2 joined by a space.

          • Notesstring

            Notes for the warehouse; when the address has a company, "Company: <name>" is appended.

      • ProductListarray of objectrequired

        Only the lines allocated to this warehouse, with the open quantity.

        Attributes of each item
        • Skustringrequired

          Item key (EAN by default).

          Example: 8000000000017
        • Quantityintegerrequired
          min 1
    • StatusCode201required
    • Successtruerequired
    • Messagestringrequired
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 405Known path called with the wrong method.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X GET https://api-commerce.nucleoplatform.com/V1/Orders/New \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Accept: application/json'
Response
{
  "Content": [
    {
      "OrderData": {
        "OmsOrderNumber": "#1042",
        "OmsCustomerId": "7712345678",
        "OrderDateTime": "2026-10-05T08:12:30Z",
        "HasExternalDocuments": "false",
        "PreparationType": "001",
        "OrderType": "B2C",
        "SelectedCourier": "GLS",
        "Priority": 3,
        "UserLanguage": "it-IT",
        "ShipmentType": 1
      },
      "ShippingData": {
        "FirstName": "Giulia",
        "LastName": "Bianchi",
        "EmailAddress": "giulia.bianchi@example.com",
        "PhoneNumber": "+39 333 0000000",
        "Address": {
          "City": "Milano",
          "CountryCode": "IT",
          "PostalCode": "20121",
          "StateOrProvinceCode": "MI",
          "Street": "Via Roma 1 Scala B",
          "Notes": "Ring twice — Company: Acme Apparel Srl"
        }
      },
      "ProductList": [
        {
          "Sku": "8000000000017",
          "Quantity": 1
        },
        {
          "Sku": "8000000000024",
          "Quantity": 2
        }
      ]
    }
  ],
  "StatusCode": 201,
  "Success": true,
  "Message": ""
}
post/V1/Orders/Acknowledge

Accept or reject orders

Confirms (or rejects) that the warehouse took over one or more orders. Accepts a single object or an array.

  • Success: true → the order is acknowledged, leaves Orders/New, and WmsOrderNumber is stored and shown on the order. From now on Nucleo no longer subtracts the order from your stock: your next stock levels must already exclude it.
  • Success: false → the order is rejected by the warehouse with the code in ErrorcCode; the merchant is alerted, fixes the order and re-releases it, and it reappears in Orders/New.
  • If the order was cancelled on the sales channel between your download and your acknowledgement, the acknowledgement is accepted but the merchant is alerted to stop the order with you manually (the contract has no cancel call towards the WMS).

Validation first: every item is checked before any is applied; an unknown order (or an order not allocated to this warehouse) or a non-boolean Success rejects the whole call with 400.

Idempotent: repeating the same acknowledgement has no further effect.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Orders/Acknowledge
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

One of the following shapes:

OrderAcknowledge
  • OmsOrderNumberstringrequired
    Example: #1042
  • WmsOrderNumberstring

    Warehouse order reference, stored and shown on the order.

    Example: WMS-778812
  • Successboolean | string | integerrequired

    true = taken over, false = rejected. Accepts true/false, "True"/"False", 1/0.

  • ErrorcCodestring

    Rejection code when Success is false. ErrorCode is accepted too.

    Example: 002
array of OrderAcknowledge
  • OmsOrderNumberstringrequired
    Example: #1042
  • WmsOrderNumberstring

    Warehouse order reference, stored and shown on the order.

    Example: WMS-778812
  • Successboolean | string | integerrequired

    true = taken over, false = rejected. Accepts true/false, "True"/"False", 1/0.

  • ErrorcCodestring

    Rejection code when Success is false. ErrorCode is accepted too.

    Example: 002

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body or unknown order; nothing applied.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Orders/Acknowledge \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "OmsOrderNumber": "#1042",
    "WmsOrderNumber": "WMS-778812",
    "Success": true,
    "ErrorcCode": ""
  },
  {
    "OmsOrderNumber": "#1043",
    "WmsOrderNumber": "",
    "Success": false,
    "ErrorcCode": "002"
  }
]'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Orders/Processed

Report picked quantities and parcels

Picking is complete, fully or partially. Send the picked quantity per item (with lot and serial when relevant) and the parcels with weight and dimensions.

  • The order moves to Processed; picked quantities, lots, serials and parcels are stored.
  • A line picked for less than its open quantity is marked unfulfillable for the difference and the merchant is alerted (partial fulfilment). Refunding unfulfilled lines is done by the merchant, or automatically if they enabled it.
  • Quantities are matched to lines by item key; several ProductList entries for the same Sku are summed.
  • Send it before Orders/Shipped: the shipped quantities are the picked ones.

Idempotent: repeating the call replaces the previous values, it does not add to them.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Orders/Processed
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired
    Example: #1042
  • EventDateTimestring (date-time)

    End of picking. Defaults to now.

  • ParcelQtyinteger

    Number of parcels. Defaults to the size of ParcelList.

    min 1
  • ProductListarray of object
    Attributes of each item
    • Skustringrequired
    • Quantityintegerrequired
      min 0
    • LotNumberstring
    • LotExpirationDatestring
    • SerialNumberstring
  • ParcelListarray of object
    Attributes of each item
    • idParcelstring

      Warehouse parcel id.

    • CourierLabelIdstring

      Parcel tracking number.

    • ParcelWeightGrnumber
    • ParcelHeightMmnumber
    • ParcelWidthMmnumber
    • ParcelDepthMmnumber

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body (not a JSON object) or order unknown / not allocated to this warehouse.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Orders/Processed \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1042",
  "EventDateTime": "2026-10-05T16:54:40.408+02:00",
  "ParcelQty": 2,
  "ProductList": [
    {
      "Sku": "8000000000017",
      "Quantity": 1,
      "LotNumber": "",
      "LotExpirationDate": "",
      "SerialNumber": ""
    },
    {
      "Sku": "8000000000024",
      "Quantity": 1
    }
  ],
  "ParcelList": [
    {
      "idParcel": "WmsId.0AA01",
      "CourierLabelId": "GLS0000000001",
      "ParcelWeightGr": 820,
      "ParcelHeightMm": 120,
      "ParcelWidthMm": 300,
      "ParcelDepthMm": 400
    },
    {
      "idParcel": "WmsId.0AA02",
      "CourierLabelId": "GLS0000000002",
      "ParcelWeightGr": 410,
      "ParcelHeightMm": 100,
      "ParcelWidthMm": 250,
      "ParcelDepthMm": 350
    }
  ]
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Orders/Shipped

Report shipment with courier and waybill

The order left the warehouse.

  • The order moves to Shipped; Nucleo records courier, waybill, total weight and volume, and the return waybill.
  • Shipped quantities are those reported in Orders/Processed; without it, all open lines allocated to this warehouse.
  • Nucleo creates the fulfilment on the sales channel with courier and tracking; the shipping email to the customer follows the merchant's channel settings. CourierCode is translated to the channel's carrier name when the merchant has mapped it (for example DHL → DHL Express); unknown codes are passed through as they are.
  • With an empty TrackingUrl, Nucleo builds the tracking link from the carrier when it knows how.
  • NeedsCloseWorkDay is recorded; it has an effect only when courier labels are managed by Nucleo.
  • If the order was being cancelled, the shipment is recorded anyway and the merchant is alerted.

CourierCode and CourierWaybill are required when the courier is managed by the warehouse (the default).

Idempotent: the same call repeated with the same CourierWaybill creates no second shipment and no second email.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Orders/Shipped
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired
    Example: #1042
  • EventDateTimestring (date-time)

    Shipping time. Defaults to now.

  • CourierCodestring

    Carrier actually used. Required when the courier is managed by the warehouse.

    Example: GLS
  • CourierWaybillstring

    Waybill / tracking number. Required when the courier is managed by the warehouse.

  • ReturnCourierCodestring
  • ReturnCourierWaybillstring
  • NeedsCloseWorkDayboolean | string

    Recorded; relevant only with Nucleo-managed labels.

  • ShipmentTotalWeightGrnumber
  • ShipmentTotalVolumeCm3number
  • TrackingUrlstring

    Empty = Nucleo builds the link from the carrier when it can.

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body, unknown order or missing courier data.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Orders/Shipped \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1042",
  "EventDateTime": "2026-10-05T18:00:00+02:00",
  "CourierCode": "GLS",
  "CourierWaybill": "GLS0000000001",
  "ReturnCourierCode": "GLS",
  "ReturnCourierWaybill": "GLS0000000099",
  "NeedsCloseWorkDay": "False",
  "ShipmentTotalWeightGr": 1230,
  "ShipmentTotalVolumeCm3": 6000,
  "TrackingUrl": ""
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Orders/Canceled

Declare an order unfulfillable

The warehouse cannot fulfil the order. The order moves to Cancelled by warehouse and the merchant is alerted to cancel and refund it on the sales channel (automatically, if the merchant enabled it; no restock is made, stock comes from your next Stock/Update). Alias: POST /V1/Orders/Cancel.

Idempotent: repeating the call has no further effect. On an order whose state no longer allows a cancellation (for example already shipped) Nucleo answers 500 Internal error (ref …).

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Orders/Canceled
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired

    Order name.

    Example: #1042
  • EventDateTimestring (date-time)

    When the warehouse declared it unfulfillable. Defaults to now.

    Example: 2026-10-05T11:20:00+02:00

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body (not a JSON object) or order unknown / not allocated to this warehouse.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Orders/Canceled \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1043",
  "EventDateTime": "2026-10-05T11:20:00+02:00"
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Orders/Cancel

Declare an order unfulfillable (alias)

Alias of POST /V1/Orders/Canceled, same body, behaviour and responses.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Orders/Cancel
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired

    Order name.

    Example: #1042
  • EventDateTimestring (date-time)

    When the warehouse declared it unfulfillable. Defaults to now.

    Example: 2026-10-05T11:20:00+02:00

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body (not a JSON object) or order unknown / not allocated to this warehouse.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Orders/Cancel \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1043",
  "EventDateTime": "2026-10-05T11:20:00+02:00"
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}

Stock

Push stock levels from the warehouse.

post/V1/Stock/Update

Push stock levels (POST)

Same as PUT /V1/Stock/Update, for clients that cannot send PUT.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Stock/Update
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • IdWarehousestring

    Warehouse code. Defaults to the code configured on the connection (001).

    Example: 001
  • ProductListarray of objectrequired

    Array of items, or an object wrapping the array.

    Attributes of each item
    • Skustringrequired
      Example: 8000000000017
    • StockLevelnumberrequired

      Absolute quantity (integer part is used).

      Example: 100
    • Classificationstring

      Sellable (default) or another class such as Unsellable. Case-insensitive.

      Example: Sellable
    • EventDateTimestring (date-time)

      When the level was computed; older values than the last applied are ignored.

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body or invalid item; nothing stored.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Stock/Update \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "IdWarehouse": "001",
  "ProductList": [
    {
      "Sku": "8000000000017",
      "StockLevel": 100,
      "Classification": "Sellable",
      "EventDateTime": "2026-10-05T10:00:00.408+02:00"
    },
    {
      "Sku": "8000000000017",
      "StockLevel": 3,
      "Classification": "Unsellable",
      "EventDateTime": "2026-10-05T10:00:00+02:00"
    },
    {
      "Sku": "8000000000024",
      "StockLevel": 0,
      "Classification": "Sellable",
      "EventDateTime": "2026-10-05T10:00:00+02:00"
    }
  ]
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
put/V1/Stock/Update

Push stock levels

Absolute stock levels per item, classification and warehouse. POST is accepted as well as PUT.

  • StockLevel is an absolute quantity, not a variation. It must already exclude the orders you have acknowledged. Nucleo subtracts the orders you have not acknowledged yet, then publishes availability to the sales channels.
  • Send everything or only what changed: items not sent are not zeroed. To zero an item, send it with StockLevel: 0.
  • Only Sellable (case-insensitive; the default when missing) counts as sellable. Other classifications (for example Unsellable) are stored separately.
  • Out-of-order protection: a value whose EventDateTime is older than the last one applied for the same item and classification is ignored (the call still answers Success).
  • An unknown Sku is skipped and the merchant is alerted; the rest of the call is applied.
  • IdWarehouse defaults to the warehouse code configured on the connection (001 unless the merchant changed it).
  • Success means the levels are stored; publication to the channels follows asynchronously.

Idempotent: repeating the call re-applies the same values.

Rate limit: shared 600 calls/minute per connection.

PUT https://api-commerce.nucleoplatform.com/V1/Stock/Update
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • IdWarehousestring

    Warehouse code. Defaults to the code configured on the connection (001).

    Example: 001
  • ProductListarray of objectrequired

    Array of items, or an object wrapping the array.

    Attributes of each item
    • Skustringrequired
      Example: 8000000000017
    • StockLevelnumberrequired

      Absolute quantity (integer part is used).

      Example: 100
    • Classificationstring

      Sellable (default) or another class such as Unsellable. Case-insensitive.

      Example: Sellable
    • EventDateTimestring (date-time)

      When the level was computed; older values than the last applied are ignored.

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body or invalid item; nothing stored.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X PUT https://api-commerce.nucleoplatform.com/V1/Stock/Update \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "IdWarehouse": "001",
  "ProductList": [
    {
      "Sku": "8000000000017",
      "StockLevel": 100,
      "Classification": "Sellable",
      "EventDateTime": "2026-10-05T10:00:00.408+02:00"
    },
    {
      "Sku": "8000000000017",
      "StockLevel": 3,
      "Classification": "Unsellable",
      "EventDateTime": "2026-10-05T10:00:00+02:00"
    },
    {
      "Sku": "8000000000024",
      "StockLevel": 0,
      "Classification": "Sellable",
      "EventDateTime": "2026-10-05T10:00:00+02:00"
    }
  ]
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}

Returns

Download expected returns, acknowledge them, report the inspection outcome.

get/V1/Returns/New

List expected returns

Returns announced by the customer and expected at this warehouse, not yet acknowledged. A return is routed to the warehouse of its return location when the merchant set one, otherwise to the warehouse that shipped the order. No parameters.

  • A return is listed at every call until Returns/Acknowledge arrives (positive or negative).
  • At most 500 per call, oldest first. Reading has no side effect.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/V1/Returns/New
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Responses

  • 200Expected returns (possibly none).
    • Contentarray of objectrequired
      max items 500
      Attributes of each item
      • OmsOrderNumberstring
        Example: #1042
      • OmsReturnNumberstring
        Example: #1042-R1
      • EventDateTimestring (date-time)

        Return creation time, UTC.

      • ProductListarray of object
        Attributes of each item
        • Skustring
        • QuantityReturnedinteger
          min 1
    • Successtruerequired
    • ErrorMessagestringrequired
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 405Known path called with the wrong method.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X GET https://api-commerce.nucleoplatform.com/V1/Returns/New \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Accept: application/json'
Response
{
  "Content": [
    {
      "OmsOrderNumber": "#1042",
      "OmsReturnNumber": "#1042-R1",
      "EventDateTime": "2026-10-07T07:41:02Z",
      "ProductList": [
        {
          "Sku": "8000000000017",
          "QuantityReturned": 1
        }
      ]
    }
  ],
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Returns/Acknowledge

Accept or reject expected returns

Single object or array. With Success: true the return becomes awaited at warehouse; with Success: false it stays in Nucleo with your code and the merchant is alerted. In both cases it leaves Returns/New.

Validation first: an unknown return or a non-boolean Success rejects the whole call with 400.

Idempotent: repeating the call has no further effect.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Returns/Acknowledge
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

One of the following shapes:

ReturnAcknowledge
  • OmsReturnNumberstringrequired
    Example: #1042-R1
  • Successboolean | string | integerrequired

    Accepts true/false, "True"/"False", 1/0.

  • ErrorcCodestring

    Rejection code. ErrorCode is accepted too.

array of ReturnAcknowledge
  • OmsReturnNumberstringrequired
    Example: #1042-R1
  • Successboolean | string | integerrequired

    Accepts true/false, "True"/"False", 1/0.

  • ErrorcCodestring

    Rejection code. ErrorCode is accepted too.

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body or unknown return; nothing applied.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Returns/Acknowledge \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsReturnNumber": "#1042-R1",
  "Success": true,
  "ErrorcCode": ""
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Return/Update

Report the inspection outcome of a return

Per-line outcome once the parcel has been received and inspected. Alias: POST /V1/Returns/Update.

  • ExternalReference1 must carry the OmsReturnNumber of the expected return.
  • The return is compliant when exactly the expected items and quantities arrived and every received line is Sellable; Nucleo records the positive outcome and forwards it for the customer refund. Otherwise it is not compliant and goes to the merchant's customer service. A line without Classification makes it not compliant.
  • ReturnCode is stored on the line and, when the merchant mapped it, sets the return reason.
  • If ExternalReference1 matches no expected return of that order (a parcel arrived unannounced), Nucleo creates an unannounced return on the order and alerts the merchant.
  • If the return had been cancelled or already closed, the goods are recorded, the status does not change and the merchant is alerted.
  • AquisitionDateTime is spelt as in the T-Data contract (no "c").

Idempotent: a second call on the same return recomputes the outcome; repeating the same unannounced return does not create a second one.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Return/Update
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired
    Example: #1042
  • EventDateTimestring (date-time)

    End of inspection.

  • AquisitionDateTimestring (date-time)

    Parcel reception (spelling as in the T-Data contract).

  • ExternalReference1string

    OmsReturnNumber of the expected return; unknown = unannounced return.

    Example: #1042-R1
  • ExternalReference2string
  • ProductListarray of objectrequired

    Array of items, or an object wrapping the array (a single object is also accepted).

    Attributes of each item
    • Skustringrequired
    • QuantityReturnedinteger

      Quantity is accepted too.

      min 0
    • Classificationstring

      Sellable or another class. Missing = not compliant.

    • ReturnCodestring

      Return reason code from the parcel form.

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body, unknown order or item without Sku.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Return/Update \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1042",
  "EventDateTime": "2026-10-09T16:54:40.408+02:00",
  "AquisitionDateTime": "2026-10-09T09:10:00+02:00",
  "ExternalReference1": "#1042-R1",
  "ExternalReference2": "",
  "ProductList": [
    {
      "Sku": "8000000000017",
      "QuantityReturned": 1,
      "Classification": "Sellable",
      "ReturnCode": ""
    }
  ]
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Returns/Update

Report the inspection outcome (alias)

Alias of POST /V1/Return/Update, same body, behaviour and responses.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Returns/Update
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired
    Example: #1042
  • EventDateTimestring (date-time)

    End of inspection.

  • AquisitionDateTimestring (date-time)

    Parcel reception (spelling as in the T-Data contract).

  • ExternalReference1string

    OmsReturnNumber of the expected return; unknown = unannounced return.

    Example: #1042-R1
  • ExternalReference2string
  • ProductListarray of objectrequired

    Array of items, or an object wrapping the array (a single object is also accepted).

    Attributes of each item
    • Skustringrequired
    • QuantityReturnedinteger

      Quantity is accepted too.

      min 0
    • Classificationstring

      Sellable or another class. Missing = not compliant.

    • ReturnCodestring

      Return reason code from the parcel form.

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body, unknown order or item without Sku.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Returns/Update \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1042",
  "EventDateTime": "2026-10-09T16:54:40.408+02:00",
  "AquisitionDateTime": "2026-10-09T09:10:00+02:00",
  "ExternalReference1": "#1042-R1",
  "ExternalReference2": "",
  "ProductList": [
    {
      "Sku": "8000000000017",
      "QuantityReturned": 1,
      "Classification": "Sellable",
      "ReturnCode": ""
    }
  ]
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
post/V1/Returns/Canceled

Cancel an expected return

The expected return will not arrive. It moves to Cancelled and the cancellation is forwarded to the merchant's returns provider. If the parcel arrives anyway, a later Return/Update records the goods and alerts the merchant.

Idempotent: repeating the call has no further effect.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Returns/Canceled
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsReturnNumberstringrequired
    Example: #1042-R1
  • EventDateTimestring (date-time)
  • Reasonstring

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body or unknown return.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Returns/Canceled \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsReturnNumber": "#1042-R1",
  "EventDateTime": "2026-10-08T10:00:00+02:00",
  "Reason": "The customer did not ship the parcel"
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}

Labels and documents

Optional services, off by default. Courier labels generated by Nucleo, order documents and the WMS item registry.

get/V1/Labels/Get

Download courier labels generated by Nucleo

Optional, off by default. Available only when the merchant set the connection to have courier labels managed by Nucleo; otherwise it answers 404 Labels are managed by the WMS.

Label numbering: IdLabel 0 is the return label (Position Internal, to put inside the parcel), 1 is the first parcel (generated when the order is first returned by Orders/New), 2–10 are additional parcels (created by Labels/Add or by Orders/Processed with ParcelQty > 1).

Without IdLabel all labels of the order are returned. If any requested label is still being generated the answer is the business error LabelNotReady (HTTP 200): retry a little later. FileType is always Zpl; Content is base64.

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/V1/Labels/Get
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • OmsOrderNumberstringrequired

    Order name, # encoded as %23.

    Example: #1042
  • IdLabelinteger

    A single label, 0–10.

    min 0max 10
    Example: 1

Responses

  • 200Labels, or the business error LabelNotReady.

    One of the following shapes:

    FilesResponse
    • Status"success"required
    • Messagestringrequired
      Example: File retrieved successfully.
    • Dataarray of objectrequired
      Attributes of each item
      • IdLabelinteger

        Labels only. 0 return label, 1 first parcel, 2–10 additional parcels.

      • idParcelstring | null

        Labels only.

      • CourierLabelIdstring | null

        Labels only. Tracking number.

      • IdDocumentstring

        Documents only.

      • Positionstring
        One ofInternalExternal
      • FileTypestring

        Zpl for labels; A4 (or the stored type) for documents.

      • Contentstring
    BusinessError
    • ErrorCodestringrequired
      One ofLabelNotReadyLabelAlreadyAddedDocumentNotReady
    • successfalserequired
  • 400Unknown order or label.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 404Labels are produced by the warehouse for this connection (default).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X GET 'https://api-commerce.nucleoplatform.com/V1/Labels/Get?OmsOrderNumber=%231042&IdLabel=1' \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Accept: application/json'
Response
{
  "Status": "success",
  "Message": "File retrieved successfully.",
  "Data": [
    {
      "IdLabel": 0,
      "idParcel": null,
      "CourierLabelId": "GLS0000000099",
      "Position": "Internal",
      "FileType": "Zpl",
      "Content": "XlhBXkZPNTAsNTBeQURO..."
    },
    {
      "IdLabel": 1,
      "idParcel": "WmsId.0AA01",
      "CourierLabelId": "GLS0000000001",
      "Position": "External",
      "FileType": "Zpl",
      "Content": "XlhBXkZPNTAsNTBeQURO..."
    }
  ]
}
post/V1/Labels/Add

Request an additional parcel label

Optional, off by default (see Labels/Get). Generates label IdLabel (0–10) for the order. Then download it with Labels/Get.

Business errors (HTTP 200): LabelAlreadyAdded when that label exists already, LabelNotReady when the carrier did not return it yet (retry Labels/Get later).

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Labels/Add
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • OmsOrderNumberstringrequired
    Example: #1042
  • IdLabelintegerrequired
    min 0max 10
    Example: 2

Responses

  • 200Label generated, or a business error.

    One of the following shapes:

    Ok
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
    BusinessError
    • ErrorCodestringrequired
      One ofLabelNotReadyLabelAlreadyAddedDocumentNotReady
    • successfalserequired
  • 400Missing or invalid fields.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 404Labels are produced by the warehouse for this connection (default).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Labels/Add \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "OmsOrderNumber": "#1042",
  "IdLabel": 2
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}
get/V1/Documents/Get

Download documents to print for an order

Optional, off by default: answers 404 Documents are not enabled until the merchant enables documents.

Returns the documents to print for the order: the merchant's active templates in the destination language (for example a packing note) and the order's own documents (for example invoices for non-EU destinations). Position says where the document goes (Internal inside the parcel, External on the outside). Content is a base64 file.

When documents are enabled, an order whose destination needs external documents (by default CH and GB) appears in Orders/New with HasExternalDocuments: "true" only once they are ready; until then this endpoint answers the business error DocumentNotReady (HTTP 200).

Rate limit: shared 600 calls/minute per connection.

GET https://api-commerce.nucleoplatform.com/V1/Documents/Get
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Query parameters

  • OmsOrderNumberstringrequired

    Order name, # encoded as %23.

    Example: #1042

Responses

  • 200Documents, or the business error DocumentNotReady.

    One of the following shapes:

    FilesResponse
    • Status"success"required
    • Messagestringrequired
      Example: File retrieved successfully.
    • Dataarray of objectrequired
      Attributes of each item
      • IdLabelinteger

        Labels only. 0 return label, 1 first parcel, 2–10 additional parcels.

      • idParcelstring | null

        Labels only.

      • CourierLabelIdstring | null

        Labels only. Tracking number.

      • IdDocumentstring

        Documents only.

      • Positionstring
        One ofInternalExternal
      • FileTypestring

        Zpl for labels; A4 (or the stored type) for documents.

      • Contentstring
    BusinessError
    • ErrorCodestringrequired
      One ofLabelNotReadyLabelAlreadyAddedDocumentNotReady
    • successfalserequired
  • 400Unknown order.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 404Documents are not enabled for this connection (default).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X GET 'https://api-commerce.nucleoplatform.com/V1/Documents/Get?OmsOrderNumber=%231042' \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Accept: application/json'
Response
{
  "Status": "success",
  "Message": "File retrieved successfully.",
  "Data": [
    {
      "IdDocument": "PackingNote",
      "Position": "Internal",
      "FileType": "A4",
      "Content": "JVBERi0xLjQK..."
    },
    {
      "IdDocument": "Invoice1042",
      "Position": "External",
      "FileType": "A4",
      "Content": "JVBERi0xLjQK..."
    }
  ]
}
post/V1/Catalogue

Register WMS item codes against EANs

Optional, off by default: answers 404 Catalogue is not enabled unless the merchant identifies items by a WMS code instead of the EAN. Upserts the WMS item registry (Sku ↔ EAN, title, category, weight and dimensions). An EAN not found in the merchant catalogue is stored and the merchant is alerted.

Idempotent: items are upserted by Sku.

Rate limit: shared 600 calls/minute per connection.

POST https://api-commerce.nucleoplatform.com/V1/Catalogue
Authentication: X-Api-Key header or Bearer token or HTTP Basic
Rate limit: 600 requests per 1m, per key

Request bodyapplication/json

  • IdWarehousestring
  • ProductListarray of objectrequired
    Attributes of each item
    • Skustringrequired

      WMS item code.

    • EANstring
    • Titlestring
    • Categorystring
    • WeightGrnumber
    • HeightMmnumber
    • WidthMmnumber
    • DepthMmnumber

Responses

  • 200Accepted.
    • Successtruerequired
    • ErrorMessagestringrequired
      Example:
  • 400Invalid body or item.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 401Missing or wrong credentials. No WWW-Authenticate header is sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 403The caller IP is not in the connection allowlist (only when the merchant set one).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 404Catalogue registry not enabled for this connection (default).
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 429More than 600 calls in a minute on this connection, or more than 30 failed authentications in 5 minutes from this IP. No Retry-After or X-RateLimit-* headers are sent.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
  • 500Connection paused or still a draft (nothing read or written, retry later), or unexpected error with a reference.
    • ErrorCode"Exception"required
    • Messagestringrequired
      Example: Order not found: #9999
Request
curl -X POST https://api-commerce.nucleoplatform.com/V1/Catalogue \
  -H "X-Api-Key: $NUCLEO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "IdWarehouse": "001",
  "ProductList": [
    {
      "Sku": "TEE-BLK-M",
      "EAN": "8000000000017",
      "Title": "T-shirt Black M",
      "Category": "T-shirts",
      "WeightGr": 180,
      "HeightMm": 20,
      "WidthMm": 250,
      "DepthMm": 300
    }
  ]
}'
Response
{
  "Success": true,
  "ErrorMessage": ""
}