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"}'
{
"redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "cancellation_requested"
}
Redemptions
Cancel Redemption
Requests cancellation of a submitted redemption. Only valid before ORO starts physical preparation.
POST
/
v1
/
redemptions
/
{id}
/
cancel
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"}'
{
"redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "cancellation_requested"
}
Overview
Flags a redemption for cancellation. Only valid when the redemption is atsubmitted. 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.
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.Headers
string
required
A valid
PARTNER scope key.Path Parameters
string
required
Redemption identifier (prefixed
red_).Request Body
string
Free-form string explaining the cancel. Stored on the redemption row as
cancellation_reason.Response
string
Echo of the path parameter.
string
Always
"cancellation_requested" on success.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 |
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"}'
{
"redemption_id": "red_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"status": "cancellation_requested"
}