> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/v2/returns/rma-actions-api/edit-return-api.md).

# Edit Return API

Production endpoint URL:

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

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 %}

### Supported Operation

Currently supported:

* `cancel_exchange`

### What `cancel_exchange` Achieves

This operation reverts an exchange-oriented return back to refund-oriented processing.

When successful, it may:

* Convert exchange compensation methods to `refund`
* Clear uneven-exchange items
* Ensure a refund method exists (defaults to `original-payment-method` if missing)
* Attempt to delete related Shopify draft order
* Remove stored Shopify draft-order references from return data
* Propagate changes to backend tracking
* Tag Shopify order with `parcellab_exchange_cancelled` (best effort)

### Request

#### Headers

| Header         | Required | Type                        |
| -------------- | -------- | --------------------------- |
| `user`         | yes      | string                      |
| `Content-Type` | yes      | string (`application/json`) |

#### JSON Body

| Field                           | Required | Type   | Rules                     | Description                                          |
| ------------------------------- | -------- | ------ | ------------------------- | ---------------------------------------------------- |
| `returnId`                      | yes      | string | 24-character ID           | Return to edit.                                      |
| `lang`                          | yes      | string | min length 1              | Language context.                                    |
| `country`                       | yes      | string | min length 1              | Country/market context.                              |
| `operation`                     | yes      | string | must be `cancel_exchange` | Edit operation.                                      |
| `draft`                         | no       | string | optional                  | Set to `true` for draft config.                      |
| `operationPayload`              | no       | object | optional                  | Operation-specific payload.                          |
| `operationPayload.cancelReason` | no       | string | optional                  | Currently accepted, not persisted by this operation. |

### Example Request

```bash
curl \
  -X POST "https://returns-api.parcellab.com/prod/editReturnById" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "operation": "cancel_exchange",
    "operationPayload": {
      "cancelReason": "Customer requested refund instead of exchange"
    }
  }'
```

### Success Responses (`200 OK`)

#### Updated

```json
{
  "returnId": "af0000000000000000000001",
  "operation": "cancel_exchange",
  "action": "updated",
  "shopifyDraftOrder": {
    "attempted": true,
    "cancelled": true,
    "error": null
  },
  "exchangeArticlesUpdated": 2,
  "exchangeItemsUpdated": 2,
  "refundMethod": "original-payment-method",
  "refundMethodApplied": true,
  "draftOrderIdRemoved": true,
  "unevenExchangeArticlesCleared": 1,
  "backendTrackingUpdated": true,
  "shopifyDraftOrderDataCleared": true
}
```

#### Skipped

```json
{
  "returnId": "af0000000000000000000001",
  "operation": "cancel_exchange",
  "action": "skipped",
  "reason": "return_already_closed",
  "shopifyDraftOrder": {
    "attempted": false,
    "cancelled": false,
    "error": null
  }
}
```

Common `reason` values:

* `return_already_closed`
* `no_changes_required`

### Shopify Behavior

For Shopify-connected returns:

1. If a draft order exists, deletion is attempted.
2. If draft deletion fails, the operation can still continue and return `shopifyDraftOrder.error`.
3. A Shopify order tag (`parcellab_exchange_cancelled`) is attempted in best-effort mode (tag failure does not fail the endpoint).

### Error Responses

<table><thead><tr><th width="104.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>Invalid request body format.</code></td><td>Invalid JSON body.</td></tr><tr><td><code>400</code></td><td><code>Update return failed.</code></td><td>Persisting return changes failed.</td></tr><tr><td><code>400</code></td><td><code>No modifiers to update is set</code></td><td>No valid state change could be applied.</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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.