/

Contents

Returns

Returns the customer is sending back to your warehouse, the confirmation that you expect them, what actually arrived and in which condition, and parcels nobody announced.

A return is compliant when every expected item arrived in the expected quantity and in sellable condition; otherwise it is not compliant and the merchant's customer service is alerted.

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

Endpoints

get/returnsList returns
get/returns/{id}Get a return
post/returns/{id}/acceptConfirm an expected return
post/returns/{id}/receiptReport what arrived
post/returns/unannouncedReport an unannounced return
hookreturn.expectedA return is coming to your warehouse

get/returns

What arrived, item by item, with its condition. On the first receipt, expected items you do not list count as received 0; items that were not expected are added and make the return not compliant. Several lines of the same item in different conditions are allowed. A later receipt updates only the items it lists (the others keep what you reported before): to correct, list every item again.

The return becomes received with an outcome: compliant when quantities match and everything is sellable, not_compliant otherwise (the merchant's customer service is alerted). Sending a new receipt re-evaluates the outcome. A receipt for a cancelled or closed return is recorded, its status does not change and the merchant is alerted.

POST https://api-commerce.nucleoplatform.com/api/fulfillment/v1/returns/{id}/receipt

Authentication: Bearer token

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

Path parameters

idstringrequired
Return number (as in number) or return ID.

Example: R1042-1

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 request — same method, same path written the same way (/orders/1042 and /orders/%231042 differ) and same body — returns the stored answer without doing the work again (header Idempotent-Replayed: true; the replayed body keeps the original request_id, the X-Request-Id header is the new call's). The same key with a different request 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. Server errors (5xx) and 429 are not stored: retry them with the same key.

max length 255
Example: 2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f

Request bodyapplication/json

received_atstring (date-time) | null
linesarray of ItemRef & objectrequired
min items 1max items 500
Attributes of each item
- skustring | null
  max length 255
- barcodestring | null
  max length 255
- quantityintegerrequired
  min 0
- conditionstringrequired
  One ofsellabledamageddefectiveusedwrong_item
- notestring | null
  max length 500

Responses

200The return after the change.application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Idempotent-Replayed true when the answer is the stored one of an earlier request with the same Idempotency-Key.
- idstring (uuid)
- numberstring
- statusstring
  One ofexpectedreceivedcancelled
- outcomestring | null
  One ofcompliantnot_compliantnull
- unannouncedboolean
  Created by a warehouse from a parcel nobody announced.
- order_numberstring | null
- reasonobject
  Child attributes
  codestring | null
  textstring | null
- customer_notestring | null
- return_trackingobject
  Child attributes
  carrier_codestring | null
  tracking_numberstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
- accepted_atstring (date-time) | null
- received_atstring (date-time) | null
- cancelled_atstring (date-time) | null
- linesarray of object
  Attributes of each item
  line_idstring (uuid)
  order_line_idstring (uuid) | null
  skustring | null
  barcodestring | null
  item_keystring | null
  titlestring | null
  quantity_expectedinteger
  quantity_receivedinteger | null
  conditionstring | null
  mixed when you reported the same item in more than one condition.
  
  One ofsellabledamageddefectiveusedwrong_itemmixednull
  reason_codestring | null
  notestring | null
400The request is not valid: validation_failed (with details per field), invalid_json, invalid_cursor. Nothing was changed. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
401Missing or invalid API key (unauthorized).application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
403The connection is paused (connection_paused) or not active yet (connection_not_active). Nothing was read or changed: retry later. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
404order_not_found or return_not_found — it does not exist or it belongs to another warehouse; not_found for an unknown path. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
409The request conflicts with the current state: order_not_ready, order_not_accepted, order_already_accepted, order_cancelled, order_cancel_requested, order_already_shipped, invalid_state, documents_not_ready, labels_not_ready; or with an Idempotency-Key: idempotency_key_reused, idempotency_key_in_progress (with Retry-After). Read the order or return again before retrying. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Retry-After Seconds to wait before retrying.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
422Valid JSON that cannot be applied: unknown_item (an item that is not on the order or not known, with details per line), too_many_items, labels_not_enabled. Nothing was changed. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
429rate_limited: more calls in a minute than the connection allows (600 by default, all endpoints together; the merchant can set another limit), or too many failed authentications from your IP. Wait the seconds in Retry-After. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Retry-After Seconds to wait before retrying.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.

Request

curl -X POST https://api-commerce.nucleoplatform.com/api/fulfillment/v1/returns/R1042-1/receipt \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f' \
  -H 'Content-Type: application/json' \
  -d '{
  "received_at": "2026-10-20T10:05:00Z",
  "lines": [
    {
      "sku": "TEE-BLK-M",
      "quantity": 1,
      "condition": "sellable"
    },
    {
      "sku": "HOOD-GRY-L",
      "quantity": 1,
      "condition": "damaged",
      "note": "Stain on the left sleeve."
    }
  ]
}'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/fulfillment/v1/returns/R1042-1/receipt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "received_at": "2026-10-20T10:05:00Z",
    "lines": [
      {
        "sku": "TEE-BLK-M",
        "quantity": 1,
        "condition": "sellable"
      },
      {
        "sku": "HOOD-GRY-L",
        "quantity": 1,
        "condition": "damaged",
        "note": "Stain on the left sleeve."
      }
    ]
  }),
});
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/fulfillment/v1/returns/R1042-1/receipt', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f',
    ],
    'json' => [
        'received_at' => '2026-10-20T10:05:00Z',
        'lines' => [
            [
                'sku' => 'TEE-BLK-M',
                'quantity' => 1,
                'condition' => 'sellable',
            ],
            [
                'sku' => 'HOOD-GRY-L',
                'quantity' => 1,
                'condition' => 'damaged',
                'note' => 'Stain on the left sleeve.',
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "number": "R1042-1",
  "status": "received",
  "outcome": "not_compliant",
  "unannounced": false,
  "order_number": "#1042",
  "reason": {
    "code": "size",
    "text": "Too small"
  },
  "customer_note": null,
  "return_tracking": {
    "carrier_code": "EXAMPLE",
    "tracking_number": "064152003399"
  },
  "created_at": "2026-10-18T16:20:03Z",
  "updated_at": "2026-10-20T10:05:12Z",
  "accepted_at": "2026-10-18T16:35:00Z",
  "received_at": "2026-10-20T10:05:00Z",
  "cancelled_at": null,
  "lines": [
    {
      "line_id": "7a6b5c4d-3e2f-4a1b-9c0d-8e7f6a5b4c3d",
      "order_line_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "sku": "HOOD-GRY-L",
      "barcode": "2000000000022",
      "item_key": "2000000000022",
      "title": "Fleece Hoodie · Grey · L",
      "quantity_expected": 1,
      "quantity_received": 1,
      "condition": "damaged",
      "reason_code": "size",
      "note": "Stain on the left sleeve."
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c",
    "details": {
      "lines.0.quantity": [
        "The lines.0.quantity field must be at least 0."
      ],
      "reason_code": [
        "The reason code field is required."
      ]
    }
  }
}

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

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

{
  "error": {
    "code": "order_not_found",
    "message": "Order 1042 not found.",
    "request_id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a"
  }
}

{
  "error": {
    "code": "order_not_accepted",
    "message": "Accept order",
    "request_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

{
  "error": {
    "code": "unknown_item",
    "message": "Some lines do not match an item of this order assigned to your warehouse. Nothing was changed.",
    "request_id": "2e1d0c9b-8a7f-4e6d-9c5b-4a3f2e1d0c9b",
    "details": {
      "lines.1": [
        "Not an item of this order assigned to your warehouse."
      ]
    }
  }
}

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

post/returns/unannounced

Report an unannounced return

A parcel arrived for an order but nobody announced a return. Nucleo creates the return on the order, records what arrived (as in Report what arrived) and alerts the merchant.

Only for orders your warehouse fulfilled or expects returns of: any other order answers 404 (and the merchant is alerted that goods are in the wrong warehouse). Sending the same content again — same order, reference and lines — returns the return already created (200) instead of a new one. reference (for example the number written on the parcel) becomes the return number when it is free.

POST https://api-commerce.nucleoplatform.com/api/fulfillment/v1/returns/unannounced

Authentication: Bearer token

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

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 request — same method, same path written the same way (/orders/1042 and /orders/%231042 differ) and same body — returns the stored answer without doing the work again (header Idempotent-Replayed: true; the replayed body keeps the original request_id, the X-Request-Id header is the new call's). The same key with a different request 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. Server errors (5xx) and 429 are not stored: retry them with the same key.

max length 255
Example: 2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f

Request bodyapplication/json

order_numberstringrequired
The order the goods belong to (the # can be omitted).
referencestring | null
Your reference for the parcel.

max length 120
received_atstring (date-time) | null
linesarray of ItemRef & objectrequired
min items 1max items 500
Attributes of each item
- skustring | null
  max length 255
- barcodestring | null
  max length 255
- quantityintegerrequired
  min 0
- conditionstringrequired
  One ofsellabledamageddefectiveusedwrong_item
- notestring | null
  max length 500

Responses

200The return after the change.application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Idempotent-Replayed true when the answer is the stored one of an earlier request with the same Idempotency-Key.
- idstring (uuid)
- numberstring
- statusstring
  One ofexpectedreceivedcancelled
- outcomestring | null
  One ofcompliantnot_compliantnull
- unannouncedboolean
  Created by a warehouse from a parcel nobody announced.
- order_numberstring | null
- reasonobject
  Child attributes
  codestring | null
  textstring | null
- customer_notestring | null
- return_trackingobject
  Child attributes
  carrier_codestring | null
  tracking_numberstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
- accepted_atstring (date-time) | null
- received_atstring (date-time) | null
- cancelled_atstring (date-time) | null
- linesarray of object
  Attributes of each item
  line_idstring (uuid)
  order_line_idstring (uuid) | null
  skustring | null
  barcodestring | null
  item_keystring | null
  titlestring | null
  quantity_expectedinteger
  quantity_receivedinteger | null
  conditionstring | null
  mixed when you reported the same item in more than one condition.
  
  One ofsellabledamageddefectiveusedwrong_itemmixednull
  reason_codestring | null
  notestring | null
201Return created and received.application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- idstring (uuid)
- numberstring
- statusstring
  One ofexpectedreceivedcancelled
- outcomestring | null
  One ofcompliantnot_compliantnull
- unannouncedboolean
  Created by a warehouse from a parcel nobody announced.
- order_numberstring | null
- reasonobject
  Child attributes
  codestring | null
  textstring | null
- customer_notestring | null
- return_trackingobject
  Child attributes
  carrier_codestring | null
  tracking_numberstring | null
- created_atstring (date-time)
- updated_atstring (date-time)
- accepted_atstring (date-time) | null
- received_atstring (date-time) | null
- cancelled_atstring (date-time) | null
- linesarray of object
  Attributes of each item
  line_idstring (uuid)
  order_line_idstring (uuid) | null
  skustring | null
  barcodestring | null
  item_keystring | null
  titlestring | null
  quantity_expectedinteger
  quantity_receivedinteger | null
  conditionstring | null
  mixed when you reported the same item in more than one condition.
  
  One ofsellabledamageddefectiveusedwrong_itemmixednull
  reason_codestring | null
  notestring | null
400The request is not valid: validation_failed (with details per field), invalid_json, invalid_cursor. Nothing was changed. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
401Missing or invalid API key (unauthorized).application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
403The connection is paused (connection_paused) or not active yet (connection_not_active). Nothing was read or changed: retry later. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
404order_not_found or return_not_found — it does not exist or it belongs to another warehouse; not_found for an unknown path. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
409The request conflicts with the current state: order_not_ready, order_not_accepted, order_already_accepted, order_cancelled, order_cancel_requested, order_already_shipped, invalid_state, documents_not_ready, labels_not_ready; or with an Idempotency-Key: idempotency_key_reused, idempotency_key_in_progress (with Retry-After). Read the order or return again before retrying. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Retry-After Seconds to wait before retrying.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
422Valid JSON that cannot be applied: unknown_item (an item that is not on the order or not known, with details per line), too_many_items, labels_not_enabled. Nothing was changed. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.
429rate_limited: more calls in a minute than the connection allows (600 by default, all endpoints together; the merchant can set another limit), or too many failed authentications from your IP. Wait the seconds in Retry-After. application/json
Headers
- X-Request-Id Identifier of the call. Quote it when you contact support; it is also error.request_id.
- Retry-After Seconds to wait before retrying.
- errorobjectrequired
  Child attributes
  codestringrequired
  Stable, machine-readable code. Branch on it, not on message.
  
  One ofvalidation_failedinvalid_jsoninvalid_cursorunauthorizedconnection_pausedconnection_not_activenot_foundmethod_not_allowedorder_not_foundreturn_not_foundorder_not_readyorder_not_acceptedorder_already_acceptedorder_cancelledorder_cancel_requestedorder_already_shippedinvalid_statedocuments_not_readylabels_not_readyidempotency_key_reusedidempotency_key_in_progresspayload_too_largeunknown_itemtoo_many_itemslabels_not_enabledrate_limitedinternal_error
  messagestringrequired
  Explanation in English for people. It can change; never parse it.
  
  request_idstring (uuid)required
  Same as the X-Request-Id header.
  
  detailsobject
  Validation and item errors per field: {"lines.0.quantity": ["…"]}.

Request

curl -X POST https://api-commerce.nucleoplatform.com/api/fulfillment/v1/returns/unannounced \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Idempotency-Key: 2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f' \
  -H 'Content-Type: application/json' \
  -d '{
  "order_number": "1042",
  "reference": "PKG-55120",
  "lines": [
    {
      "sku": "TEE-BLK-M",
      "quantity": 1,
      "condition": "sellable"
    }
  ]
}'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/fulfillment/v1/returns/unannounced", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    "Idempotency-Key": "2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "order_number": "1042",
    "reference": "PKG-55120",
    "lines": [
      {
        "sku": "TEE-BLK-M",
        "quantity": 1,
        "condition": "sellable"
      }
    ]
  }),
});
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/fulfillment/v1/returns/unannounced', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Idempotency-Key' => '2f0c9a1e-6b4d-4f3a-9e7c-5d1b8a2c4e6f',
    ],
    'json' => [
        'order_number' => '1042',
        'reference' => 'PKG-55120',
        'lines' => [
            [
                'sku' => 'TEE-BLK-M',
                'quantity' => 1,
                'condition' => 'sellable',
            ],
        ],
    ],
    'http_errors' => false,
]);

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

Response

{
  "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "number": "R1042-1",
  "status": "received",
  "outcome": "not_compliant",
  "unannounced": false,
  "order_number": "#1042",
  "reason": {
    "code": "size",
    "text": "Too small"
  },
  "customer_note": null,
  "return_tracking": {
    "carrier_code": "EXAMPLE",
    "tracking_number": "064152003399"
  },
  "created_at": "2026-10-18T16:20:03Z",
  "updated_at": "2026-10-20T10:05:12Z",
  "accepted_at": "2026-10-18T16:35:00Z",
  "received_at": "2026-10-20T10:05:00Z",
  "cancelled_at": null,
  "lines": [
    {
      "line_id": "7a6b5c4d-3e2f-4a1b-9c0d-8e7f6a5b4c3d",
      "order_line_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "sku": "HOOD-GRY-L",
      "barcode": "2000000000022",
      "item_key": "2000000000022",
      "title": "Fleece Hoodie · Grey · L",
      "quantity_expected": 1,
      "quantity_received": 1,
      "condition": "damaged",
      "reason_code": "size",
      "note": "Stain on the left sleeve."
    }
  ]
}

{
  "id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
  "number": "string",
  "status": "expected",
  "outcome": "compliant",
  "unannounced": true,
  "order_number": "string",
  "reason": {
    "code": "string",
    "text": "string"
  },
  "customer_note": "string",
  "return_tracking": {
    "carrier_code": "string",
    "tracking_number": "string"
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z",
  "accepted_at": "2026-10-01T09:30:00Z",
  "received_at": "2026-10-01T09:30:00Z",
  "cancelled_at": "2026-10-01T09:30:00Z",
  "lines": [
    {
      "line_id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
      "order_line_id": "9b2f4c1e-5d7a-4e8b-9c3d-2a1f0e6b7c8d",
      "sku": "string",
      "barcode": "string",
      "item_key": "string",
      "title": "string",
      "quantity_expected": 1,
      "quantity_received": 1,
      "condition": "sellable",
      "reason_code": "string",
      "note": "string"
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c",
    "details": {
      "lines.0.quantity": [
        "The lines.0.quantity field must be at least 0."
      ],
      "reason_code": [
        "The reason code field is required."
      ]
    }
  }
}

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

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

{
  "error": {
    "code": "order_not_found",
    "message": "Order 1042 not found.",
    "request_id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a"
  }
}

{
  "error": {
    "code": "order_not_accepted",
    "message": "Accept order",
    "request_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

{
  "error": {
    "code": "unknown_item",
    "message": "Some lines do not match an item of this order assigned to your warehouse. Nothing was changed.",
    "request_id": "2e1d0c9b-8a7f-4e6d-9c5b-4a3f2e1d0c9b",
    "details": {
      "lines.1": [
        "Not an item of this order assigned to your warehouse."
      ]
    }
  }
}

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

Webhookreturn.expected

A return is coming to your warehouse

Sent when a customer return addressed to your warehouse is approved. Read it with Get a return and confirm it with Confirm an expected return.

Request Nucleo sendsapplication/json

idstring (uuid)required
Unique per event and the same on every retry. Skip an id you already handled.
typestringrequired
One oforder.readyorder.cancelledreturn.expected
created_atstring (date-time)required
dataobjectrequired
order.ready: order_id, order_number. order.cancelled: order_id, order_number, status (cancelled or cancel_requested). return.expected: return_id, return_number, order_number.

Expected response

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

Body

{
  "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "type": "return.expected",
  "created_at": "2026-10-18T16:20:03Z",
  "data": {
    "return_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "return_number": "R1042-1",
    "order_number": "#1042"
  }
}

Response

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

Was this page helpful?

List returns

Query parameters

Responses

Get a return

Path parameters

Responses

Confirm an expected return

Path parameters

Headers

Responses

Report what arrived

Path parameters

Headers

Request bodyapplication/json

Responses

Report an unannounced return

Headers

Request bodyapplication/json

Responses

A return is coming to your warehouse

Request Nucleo sendsapplication/json

Expected response