> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grail.oro.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Redemption

> Requests cancellation of a submitted redemption. Only valid before ORO starts physical preparation.

## Overview

Flags a redemption for cancellation. **Only valid when the redemption is at `submitted`.** Once ORO advances it to `preparing`, cancel is no longer allowed — any refund would be handled out-of-band.

On success, the redemption transitions to `cancellation_requested`. ORO's admin subsequently advances it to `cancelled` after confirming no physical gold has been committed.

<Warning>
  The user has already transferred their `$GOLD` to escrow at `submitted`. Cancellation after that point is a coordination question — ORO does not automatically return tokens on cancel. Reach out separately if refunds are needed.
</Warning>

## Headers

<ParamField header="x-api-key" type="string" required>
  A valid `PARTNER` scope key.
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  Redemption identifier (prefixed `red_`).
</ParamField>

## Request Body

<ParamField body="reason" type="string">
  Free-form string explaining the cancel. Stored on the redemption row as `cancellation_reason`.
</ParamField>

## Response

<ResponseField name="redemption_id" type="string">
  Echo of the path parameter.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"cancellation_requested"` on success.
</ResponseField>

## Errors

| HTTP | `error`                    | When                                                                                |
| ---- | -------------------------- | ----------------------------------------------------------------------------------- |
| 400  | `cancellation_not_allowed` | Redemption status is not `submitted` (e.g., already `preparing`, `cancelled`, etc.) |
| 401  | `unauthorized`             | Missing or invalid `x-api-key`                                                      |
| 403  | `partner_mismatch`         | Redemption belongs to a different partner                                           |
| 404  | `redemption_not_found`     | No redemption row at or past `submitted` for this id                                |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    https://grail-stack-dev.onrender.com/v1/redemptions/red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/cancel \
    -H "x-api-key: grail_partner_<hex>" \
    -H "Content-Type: application/json" \
    -d '{"reason":"user changed mind"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "cancellation_requested"
  }
  ```
</ResponseExample>