curl "https://grail-stack-dev.onrender.com/v1/redemptions?status=submitted" \
-H "x-api-key: grail_partner_<hex>"
{
"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"
}
]
}
Redemptions
List Redemptions
Lists redemptions for the authenticated partner. Excludes the internal quoted state.
GET
/
v1
/
redemptions
curl "https://grail-stack-dev.onrender.com/v1/redemptions?status=submitted" \
-H "x-api-key: grail_partner_<hex>"
{
"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"
}
]
}
Overview
Lists redemption rows for the authenticated partner, ordered bycreated_at descending. The internal quoted state is always excluded — only redemptions at submitted or later are returned.
Headers
string
required
A valid
PARTNER scope key.Query Parameters
string
Filter to a single user. If the user doesn’t exist, returns an empty list.
string
Filter by status:
submitted, preparing, ready, collected, cancellation_requested, cancelled, or failed.string
Filter by pickup city.
Response
array
Array of redemption objects — same shape as Get Redemption.
Errors
| HTTP | error | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid x-api-key |
curl "https://grail-stack-dev.onrender.com/v1/redemptions?status=submitted" \
-H "x-api-key: grail_partner_<hex>"
{
"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"
}
]
}