Update redemption order status
Move one redemption order to another status, and optionally return the trader's coins when the new status is a refund.
- Method
- PUT
- Path
https://api.returning.ai / v1/ redemption-transactions/ status - Permission
- updateRedemptionTransactionStatus
- Retries
- No Idempotency-Key; read history first
When to use this
- Your team has fulfilled a reward, and the order should show
Completed. - A reward can't be delivered, and the trader should get their coins back.
- Your fulfilment system tracks its own progress and mirrors each step onto the order.
Authentication#
- Header
Authorization: Bearer <API_KEY>- Permission
- updateRedemptionTransactionStatusShown in the dashboard as “Update Redemption Transaction Status”
Use a Community API key with updateRedemptionTransactionStatus, and keep it on your server. The key decides the community, so you can only change orders and use statuses in that community.
Behaviour#
You can move an order from any status to any active status in your community; there are no transition rules. Every successful call adds an entry to the order's status history, even when the status is unchanged. The one exception is a repeated refund to the same status. This call doesn't email the trader.
A refund happens only when refundCoins is true and the new status is in the refunded category. It credits the order's price in coins to the trader, recorded in their coin history as a refund. It also returns the voucher to the product's stock if the voucher hasn't expired. If the voucher can't be restocked, the coins are still refunded.
An order is refunded at most once. If it has ever been in a refunded status, even one set without refundCoins, a later refund returns credited: 0 and alreadyRefunded: true. Moving an order out of a refunded status doesn't take the coins back. If two requests change the same order at once, only one can credit coins, and the status that finishes last is kept.
Request#
Headers#
Body#
Send the order ID (ORD...) as transactionId. This is the order's redemptionId from the order lists, not its internal _id. Get status IDs from List redemption statuses. The field is statusID with a capital ID. Unknown fields are ignored.
ORD...) from redemptionId in the order lists. Not the order's internal _id.RuleOrder ID in your community
Eg"ORD20269268300418273"
statusID; statusId is rejected.RuleStatus ID in your community
Eg"66f000000000000000000402"
true returns the order's coins to the trader. Only allowed when the status is in the refunded category.RuleBoolean; default false
Egtrue
Updated by API.RuleUp to 500 characters
Eg"Reward out of stock"
curl --request PUT \
--url https://api.returning.ai/v1/redemption-transactions/status \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"transactionId": "ORD20269268300418273",
"statusID": "66f000000000000000000402",
"refundCoins": true,
"remark": "Reward out of stock"
}'
Response#
A 200 returns the order's new status. When you sent refundCoins: true, data.refund says whether coins moved: check credited and alreadyRefunded, not just the code.
Rulesuccess
Eg"Transaction status updated successfully"
Eg{ ... }
Eg"ORD20269268300418273"
Eg{ ... }
Eg"66f000000000000000000402"
Eg"Refunded"
Rulenew_purchase, in_progress, completed or refunded
Eg"refunded"
Eg"#EB5757"
refundCoins: true.true.0 when the order was already refunded.true when no coins moved because the order had already been refunded.REDEMPTION_TRANSACTION_REFUNDED when you sent refundCoins: true, otherwise REDEMPTION_TRANSACTION_STATUS_UPDATED.RuleREDEMPTION_TRANSACTION_REFUNDED or REDEMPTION_TRANSACTION_STATUS_UPDATED
{
"status": "success",
"code": "REDEMPTION_TRANSACTION_REFUNDED",
"message": "Transaction status updated successfully",
"data": {
"transactionId": "ORD20269268300418273",
"statusID": "66f000000000000000000402",
"status": {
"_id": "66f000000000000000000402",
"name": "Refunded",
"category": "refunded",
"color": "#EB5757"
},
"refund": {
"requested": true,
"credited": 500,
"alreadyRefunded": false
}
}
}
Errors#
401 and 403 responses, and the authentication errors 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED, carry the code in meta.code; every other error carries it in code. A 400 or 404 changes nothing. A 500 may come after the status has already changed.
Fix the request04
VALIDATION_FAILEDFix the requestdetail names it. Check the statusID spelling and send refundCoins as a JSON boolean.REDEMPTION_REQUEST_INVALIDFix the requestrefundCoins is true but the status isn't in the refunded category. Nothing changed. Pick a refunded status, or send refundCoins: false.AUTHENTICATION_REQUIREDFix the requestAuthorization: Bearer <API_KEY> with a current Community API key.API_KEY_PERMISSION_DENIEDFix the requestupdateRedemptionTransactionStatus, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys.Fix the data02
REDEMPTION_TRANSACTION_NOT_FOUNDFix the datamessage says which: Transaction not found (use the ORD... order ID from the order list, not _id) or Status not found or inactive (the status is switched off).COMMUNITY_NOT_FOUNDFix the dataRetry with backoff02
INTERNAL_ERRORRetry with backoffstatusID is not a status in your community. Check the ID with List redemption statuses. The status may already have changed, so read the status history before you retry.AUTHENTICATION_FAILEDRetry with backoff{
"status": "fail",
"code": "REDEMPTION_REQUEST_INVALID",
"message": "Cannot refund coins for this status"
}