Returns

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

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

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

Endpoints

get/returnsList returns
get/returns/{return}Get a return

get/returns

List returns

Requires the returns:read scope.

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

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

Authentication: Bearer token

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

Query parameters

statusstring
Only returns in this status.

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

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

min 1max 200default 50
Example: 50

Responses

200A page of returns.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- dataarray of Returnrequired
  Attributes of each item
  idstringrequired
  numberstring | null
  order_idstring | null
  order_numberstring | null
  statusstringrequired
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
  reason_codestring | null
  reason_textstring | null
  customer_notestring | null
  currencystring
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  created_atstring (date-time) | null
  updated_atstring (date-time) | null
  received_atstring (date-time) | null
  closed_atstring (date-time) | null
  cancelled_atstring (date-time) | null
  linesarray of objectrequired
  Attributes of each item
  skustring | null
  barcodestring | null
  titlestring | null
  quantity_requestedinteger
  quantity_receivedinteger
  reason_codestring | null
  outcomestring | null
  The condition the warehouse found — sellable, damaged, or mixed when the pieces differ; null until checked.
  
  refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- next_cursorstring | nullrequired
400The request is not valid: validation_failed (with details per parameter or field), invalid_cursor, invalid_json (the body is not a JSON object) or unknown_item (with details per line, for example lines.0). application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
401unauthorized: the key is missing or wrong, or the call comes from an IP outside the connection's allowlist.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
403The key is right but cannot do this: insufficient_scope (the key lacks the scope of the call), connection_paused or connection_not_active (the connection is paused or not turned on yet). application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
429rate_limited: wait for the seconds in Retry-After.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- Retry-After Seconds to wait before the next call.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.

Request

curl -X GET 'https://api-commerce.nucleoplatform.com/api/commerce/v1/returns?status=requested&updated_since=2026-10-13T08%3A00%3A00Z&limit=50' \
  -H "Authorization: Bearer $NUCLEO_ACCESS_TOKEN" \
  -H 'Accept: application/json'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/commerce/v1/returns?status=requested&updated_since=2026-10-13T08%3A00%3A00Z&limit=50", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-commerce.nucleoplatform.com/api/commerce/v1/returns?status=requested&updated_since=2026-10-13T08%3A00%3A00Z&limit=50', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

Response

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

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

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the orders:read scope.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

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

get/returns/{return}

Get a return

Requires the returns:read scope.

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

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

Authentication: Bearer token

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

Path parameters

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

Example: R-1042-1

Responses

200The return.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- idstringrequired
- numberstring | null
- order_idstring | null
- order_numberstring | null
- statusstringrequired
  One ofrequestedawaiting_receiptin_transitreceivedcompliantnot_compliantclosedcancelled
- reason_codestring | null
- reason_textstring | null
- customer_notestring | null
- currencystring
- totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
- created_atstring (date-time) | null
- updated_atstring (date-time) | null
- received_atstring (date-time) | null
- closed_atstring (date-time) | null
- cancelled_atstring (date-time) | null
- linesarray of objectrequired
  Attributes of each item
  skustring | null
  barcodestring | null
  titlestring | null
  quantity_requestedinteger
  quantity_receivedinteger
  reason_codestring | null
  outcomestring | null
  The condition the warehouse found — sellable, damaged, or mixed when the pieces differ; null until checked.
- refundsarray of Refund
  Attributes of each item
  idstring
  return_idstring | null
  The return it belongs to, if any.
  
  refunded_atstring (date-time) | null
  totalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  shippingMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
  linesarray of object
  Attributes of each item
  line_idstring | null
  skustring | null
  barcodestring | null
  quantityinteger
  subtotalMoney
  Child attributes
  amountstringrequired
  Decimal string with two decimals.
  
  Example: 180.00
  currencystringrequired
  ISO 4217 code.
  
  Example: EUR
401unauthorized: the key is missing or wrong, or the call comes from an IP outside the connection's allowlist.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
403The key is right but cannot do this: insufficient_scope (the key lacks the scope of the call), connection_paused or connection_not_active (the connection is paused or not turned on yet). application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
404order_not_found or return_not_found.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.
429rate_limited: wait for the seconds in Retry-After.application/json
Headers
- X-Request-Id The id of this call. Quote it if you contact support; errors repeat it as request_id.
- Retry-After Seconds to wait before the next call.
- errorobjectrequired
  Child attributes
  codestringrequired
  Machine-readable code. Branch on this, never on message.
  
  messagestringrequired
  request_idstringrequired
  detailsobject
  For validation_failed, the messages per parameter.

Request

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

const res = await fetch("https://api-commerce.nucleoplatform.com/api/commerce/v1/returns/R-1042-1", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NUCLEO_ACCESS_TOKEN}`,
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-commerce.nucleoplatform.com/api/commerce/v1/returns/R-1042-1', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NUCLEO_ACCESS_TOKEN'),
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

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

Response

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

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the orders:read scope.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

{
  "error": {
    "code": "order_not_found",
    "message": "Order 1042 not found.",
    "request_id": "1f7e3c2a-9b8d-4e6f-a5c4-3b2a1d0e9f8c"
  }
}

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

Was this page helpful?