# RMA Actions API

## API Basics

### Base URL

Production base URL: `https://returns-api.parcellab.com/prod`

Endpoint URL format: `https://returns-api.parcellab.com/prod/<endpoint>`

### Authentication

Most action endpoints in this set are **`POST`** requests. The fetch-details endpoint is a **`GET`** request.

All requests require the `user` header.

<table><thead><tr><th width="145">Header</th><th width="115.5">Required</th><th width="115.5">Type</th><th width="208.5">Description</th></tr></thead><tbody><tr><td><code>user</code></td><td>yes</td><td>string</td><td>Merchant/customer identifier assigned by parcelLab.</td></tr><tr><td><code>Content-Type</code></td><td>for JSON body requests</td><td>string</td><td>Required for <code>POST</code> requests with a JSON body. Use <code>application/json</code>.</td></tr></tbody></table>

All requests also require the following identifier in the request payload (either **JSON body** or **query parameters**, depending on the endpoint):

<table><thead><tr><th width="145">Payload key</th><th width="115.5">Required</th><th width="115.5">Type</th><th width="208.5">Description</th></tr></thead><tbody><tr><td><code>returnId</code></td><td>yes</td><td>string</td><td>Return session identifier.</td></tr></tbody></table>

### Data Access Model

The `user` and `returnId` keys are both user-facing values in this API model.

Treat `returnId` as an RMA session identifier that is:

* Valid for the specific `user`
* Valid for up to 30 days
* Randomly generated and not realistically brute-forceable

This means `returnId` can be shown to the customer as part of the return flow, but it should only be used within the intended return context.

Access checks are still enforced server-side:

* The return must belong to the provided `user`
* The return must match the provided `lang` context (where applicable)

If these checks fail, the request is rejected (`403 FORBIDDEN`).

### Response Model

Find details below on common structures of API responses.

<details>

<summary>Success responses</summary>

* Successful calls return `2xx` and a JSON object.
* Response shape is endpoint-specific.

</details>

<details>

<summary>Error responses</summary>

Most errors follow this structure:

```json
{
  "code": 400,
  "error": "Payload schema validation failed.",
  "errorMessage": "Optional additional message",
  "details": {}
}
```

**Fields**

* `code`: HTTP status code
* `error`: stable error message/code string
* `errorMessage`: optional user-friendly or upstream detail
* `details`: optional diagnostic data

**Common Error Values**

The following values appear across these return endpoints:

| Error value                         | Typical meaning                                                  |
| ----------------------------------- | ---------------------------------------------------------------- |
| `Payload schema validation failed.` | Required field missing/invalid type.                             |
| `Invalid request body format.`      | Request body is not valid JSON.                                  |
| `FORBIDDEN`                         | Return does not belong to caller/context or operation forbidden. |
| `User not found.`                   | Unknown or inactive merchant config for provided context.        |
| `Order does not exist.`             | `returnId` not found.                                            |
| `Update return failed.`             | Return update failed during persistence.                         |
| `No modifiers to update is set.`    | No valid state change could be applied.                          |

Endpoint-specific docs list additional business-specific errors.

</details>

<details>

<summary>Retry hint header</summary>

Error responses include header `x-retryable` with `true` or `false` to indicate whether retry may make sense.

</details>

## API Routes

* [Fetch Return Details API](/docs/developers/v2/returns/rma-actions-api/fetch-return-details-api.md)\
  `GET /findById`\
  Fetch the details of an existing return by return ID.
* [Add Label API](/docs/developers/v2/returns/rma-actions-api/add-label-api.md)\
  `POST /addLabelById`\
  Add an additional return label (generated or manual).
* [Edit Return API](/docs/developers/v2/returns/rma-actions-api/edit-return-api.md)\
  `POST /editReturnById`\
  Apply post-registration edit operations, currently only cancelling the exchange for an existing return in Shopify, forcing it to fall back to the specified refund method instead. If the user did not specify a preferred refund method during registration because they only opted for exchange, the refund will be issued to the original payment method.
* [Process Return API](/docs/developers/v2/returns/rma-actions-api/process-return-api.md)\
  `POST /closeById`\
  Process the return and release refund or exchange actions where applicable.
* [Cancel RMA API](/docs/developers/v2/returns/rma-actions-api/cancel-rma-api.md)\
  `POST /cancelRma`\
  Cancel an already-created return and sync cancellation state.
* [Cancel Pickup Order API](/docs/developers/v2/returns/rma-actions-api/cancel-pickup-order-api.md)\
  `POST /cancelPickUpOrder`\
  Cancel scheduled pickup and roll return back to pre-submission state
* [Reschedule Pickup Order API](/docs/developers/v2/returns/rma-actions-api/reschedule-pickup-order-api.md)\
  `POST /reschedulePickUpOrder`\
  Reschedule a pickup date/time window


---

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