# Fetch Return Details API

Production endpoint URL:

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

For details on access, view the overview here:

{% content-ref url="/pages/ECzngWMawj0hRD9NBSDr" %}
[RMA Actions API](/docs/developers/v2/returns/rma-actions-api.md)
{% endcontent-ref %}

### 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

<table><thead><tr><th width="135">Header</th><th width="129">Required</th><th>Type</th></tr></thead><tbody><tr><td><code>user</code></td><td>yes</td><td>string</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="129">Parameter</th><th width="112">Required</th><th width="112">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>returnId</code></td><td>yes</td><td>string</td><td>24-character return ID.</td></tr><tr><td><code>lang</code></td><td>yes</td><td>string</td><td>Language context.</td></tr><tr><td><code>country</code></td><td>yes</td><td>string</td><td>Country/market context.</td></tr><tr><td><code>draft</code></td><td>no</td><td>string</td><td>Set to <code>true</code> for draft config.</td></tr></tbody></table>

#### Body

No request body is required.

### Example Request

```bash
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.

```json
{
  "_id": "af0000000000000000000001",
  "user": "1612198",
  "lang": "en",
  "country": "us",
  "ref": "ORDER-1001",
  "submitted": true,
  "status": "created",
  "customer": {
    "email": "customer@example.com"
  },
  "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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/v2/returns/rma-actions-api/fetch-return-details-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.