Skip to main content
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 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.
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

​
x-api-key
string
required
A valid PARTNER scope key.

​
Path Parameters

​
id
string
required
Redemption identifier (prefixed red_).

​
Request Body

​
reason
string
Free-form string explaining the cancel. Stored on the redemption row as cancellation_reason.

​
Response

​
redemption_id
string
Echo of the path parameter.
​
status
string
Always "cancellation_requested" on success.

​
Errors

HTTPerrorWhen
400cancellation_not_allowedRedemption status is not submitted (e.g., already preparing, cancelled, etc.)
401unauthorizedMissing or invalid x-api-key
403partner_mismatchRedemption belongs to a different partner
404redemption_not_foundNo 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"
}