> 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/cancel-rma-api.md).

# Cancel RMA API

Production endpoint URL:

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

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:

* Marks the return as `cancelled`
* Stores an optional cancellation reason
* Updates return tracking status in parcelLab backend systems
* Attempts to cancel related Shopify entities (draft order and return), when they exist

### Endpoint

<table><thead><tr><th width="153.5">Property</th><th>Value</th></tr></thead><tbody><tr><td>Method</td><td><code>POST</code></td></tr><tr><td>Path</td><td><code>/cancelRma</code></td></tr><tr><td>Content type</td><td><code>application/json</code></td></tr><tr><td>Authentication</td><td><code>user</code> header (required)</td></tr></tbody></table>

### Request

#### Headers

<table><thead><tr><th width="146">Header</th><th width="119.5">Required</th><th width="107.5">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>user</code></td><td>yes</td><td>string</td><td>Merchant/customer identifier provided by parcelLab.</td></tr><tr><td><code>Content-Type</code></td><td>yes</td><td>string</td><td>Must be <code>application/json</code>.</td></tr></tbody></table>

#### Body

<table><thead><tr><th width="147">Field</th><th width="117.5">Required</th><th width="121">Type</th><th width="125">Rules</th><th>Description</th></tr></thead><tbody><tr><td><code>returnId</code></td><td>yes</td><td>string</td><td>exactly 24 characters</td><td>Return ID to cancel.</td></tr><tr><td><code>lang</code></td><td>yes</td><td>string</td><td>min length 1</td><td>Return language.</td></tr><tr><td><code>country</code></td><td>yes</td><td>string</td><td>min length 1</td><td>Market/country context.</td></tr><tr><td><code>cancelReason</code></td><td>no</td><td>string</td><td>optional</td><td>Free-text reason saved as return status reason.</td></tr></tbody></table>

#### `cancelReason` constraints

There is currently no enforced enum or structured format for `cancelReason`.

* Accepted type: `string`
* Optional field
* No predefined list of allowed values
* No regex/length restriction enforced by this endpoint

Behavior details:

* If omitted, saved status reason is `null`
* If an empty string is sent, it is treated as no reason and stored as `null`

### Example Request

```bash
curl \
  -X POST "https://returns-api.parcellab.com/prod/cancelRma" \
  -H "user: 1612198" \
  -H "Content-Type: application/json" \
  -d '{
    "returnId": "af0000000000000000000001",
    "lang": "en",
    "country": "us",
    "cancelReason": "Customer changed mind"
  }'
```

### Success Response (`200 OK`)

```json
{
  "returnId": "af0000000000000000000001",
  "hasDraftOrder": true,
  "draftOrderCloseError": null,
  "hasReturn": true,
  "returnCloseError": null
}
```

#### Response fields

| Field                  | Type           | Meaning                                                                 |
| ---------------------- | -------------- | ----------------------------------------------------------------------- |
| `returnId`             | string         | Cancelled return ID.                                                    |
| `hasDraftOrder`        | boolean        | A Shopify draft order was found and a delete attempt was made.          |
| `draftOrderCloseError` | string \| null | Error message from Shopify draft order deletion, if deletion failed.    |
| `hasReturn`            | boolean        | A Shopify return was found and a cancel attempt was made.               |
| `returnCloseError`     | string \| null | Error message from Shopify return cancellation, if cancellation failed. |

### What It Does In Shopify

If the cancelled return is linked to Shopify, the endpoint attempts:

1. Draft order deletion (`draftOrderDelete`) when a draft order exists.
2. Return cancellation (`returnCancel`) when a Shopify return exists.

Important:

* Shopify failures do not automatically fail the whole cancellation request.
* You must inspect `draftOrderCloseError` and `returnCloseError` in the `200` response to confirm Shopify-side success.

### Error Responses

<table><thead><tr><th width="98.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 fields.</td></tr><tr><td><code>400</code></td><td><code>Invalid request body format.</code></td><td>Body is not valid JSON.</td></tr><tr><td><code>400</code></td><td><code>RMA cancel failed.</code></td><td>Upstream/customer-specific cancel export failed.</td></tr><tr><td><code>400</code></td><td><code>Update return failed.</code></td><td>Return update could not be persisted.</td></tr><tr><td><code>403</code></td><td><code>FORBIDDEN</code></td><td>Return does not belong to requesting <code>user</code> and <code>lang</code> context.</td></tr><tr><td><code>404</code></td><td><code>User not found.</code></td><td>Merchant configuration not found.</td></tr><tr><td><code>404</code></td><td><code>Order does not exist.</code></td><td>Return ID not found.</td></tr><tr><td><code>500</code></td><td>implementation-defined</td><td>Unexpected server error.</td></tr></tbody></table>

Standard error payload:

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


---

# 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/cancel-rma-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.