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

# List Redemptions

> Lists redemptions for the authenticated partner. Excludes the internal quoted state.

## Overview

Lists redemption rows for the authenticated partner, ordered by `created_at` descending. The internal `quoted` state is **always excluded** — only redemptions at `submitted` or later are returned.

## Headers

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

## Query Parameters

<ParamField query="grail_user_id" type="string">
  Filter to a single user. If the user doesn't exist, returns an empty list.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `submitted`, `preparing`, `ready`, `collected`, `cancellation_requested`, `cancelled`, or `failed`.
</ParamField>

<ParamField query="city" type="string">
  Filter by pickup city.
</ParamField>

## Response

<ResponseField name="redemptions" type="array">
  Array of redemption objects — same shape as [Get Redemption](/api-reference/redemptions/get-redemption).
</ResponseField>

## Errors

| HTTP | `error`        | When                           |
| ---- | -------------- | ------------------------------ |
| 401  | `unauthorized` | Missing or invalid `x-api-key` |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://grail-stack-dev.onrender.com/v1/redemptions?status=submitted" \
    -H "x-api-key: grail_partner_<hex>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "redemptions": [
      {
        "redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "status": "submitted",
        "denomination": "1 Tola",
        "weight_g": 11.664,
        "city": "karachi",
        "quote": {
          "spot_price_usd": 4872.84,
          "gold_value_usd": 1827.34,
          "fee_usd": 0,
          "total_usd": 1827.34,
          "tokens_required": "0.375006"
        },
        "submitted_tx_hash": "4ABC...base58",
        "created_at": "2026-04-17T11:00:00.000Z",
        "updated_at": "2026-04-17T11:00:15.000Z"
      }
    ]
  }
  ```
</ResponseExample>