Fetch Return Details API

Use this endpoint to fetch the details of an existing return by return ID.

Production endpoint URL:

https://returns-api.parcellab.com/prod/findById

For details on access, view the overview here:

RMA Actions API

What This Endpoint Achieves

When successful, the API returns the stored return process, including customer information, returned items, payment information, selected courier details, and current return status.

The endpoint may also refresh derived fields before responding, such as:

• Whether the return is still refundable

• Article-level returnability state, when configured

• Whether the return label was already used, when the confirmation-page tracking-status check is enabled

Request

Headers

Header	Required	Type
user	yes	string

Query Parameters

Parameter	Required	Type	Notes
returnId	yes	string	24-character return ID.
lang	yes	string	Language context.
country	yes	string	Country/market context.
draft	no	string	Set to true for draft config.

Body

No request body is required.

Example Request

curl \
  -X GET "https://returns-api.parcellab.com/prod/findById?returnId=af0000000000000000000001&lang=en&country=us" \
  -H "user: 1612198"

Success Response (200 OK)

The response is the return document for the requested return. The exact shape depends on the return flow and merchant configuration.

{
  "_id": "af0000000000000000000001",
  "user": "1612198",
  "lang": "en",
  "country": "us",
  "ref": "ORDER-1001",
  "submitted": true,
  "status": "created",
  "customer": {
    "email": "[email protected]"
  },
  "articles": [
    {
      "articleNo": "SKU-1001",
      "articleName": "T-Shirt",
      "quantity": 1,
      "returnReason": "fit",
      "prettyReturnReason": "Did not prefer fit"
    }
  ],
  "selectedCourierByCustomer": {
    "code": "ups",
    "prettyname": "UPS"
  },
  "isRefundable": true
}

Common response fields

Field	Type	Meaning
_id	string	Return ID.
ref	string	Original order reference.
user	string	Merchant/customer identifier.
lang	string	Return language context.
country	string	Return country/market context.
submitted	boolean	Whether the return was submitted.
status	string	Current return status.
customer	object	Customer information stored for the return.
articles	array	Items included in the return process.
selectedCourierByCustomer	object	Courier selected by the customer, if any.
returnLabel	object or array	Return label information, when label creation has run.
isRefundable	boolean	Whether the order is currently considered refundable.
returnPeriodInDays	number	Returnable period when the order is no longer refundable and a period can be derived.
isReturnInitiated	boolean	Whether the return label was already used, when tracking-status checks are enabled.
adyenPayment.uiPaymentCompleted	boolean	Payment completion status for Adyen-based payment flows, when present.

Notes

• The return must belong to the provided user.

• The return must match the provided lang context.

• Authorization is checked against the merchant configuration for the requested country and lang.

Error Responses

Status	Error value	Meaning
400	Payload schema validation failed.	Missing/invalid request input.
400	Update return failed.	Derived return fields could not be persisted before the response.
401	Security check failed.	Return authorization failed for the requested context.
401	ERROR_COUNTRY	Return country does not match the requested context or allowed-country configuration.
403	FORBIDDEN	returnId is not accessible in caller context.
404	User not found.	Merchant context not found.
404	Order does not exist.	returnId not found.
500	implementation-defined	Unexpected server error.