Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

Get redemption status by ID

Read one active redemption order status in your community by its ID, with its name, category and colour.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/redemption-transactions/status/detail
Permission
getRedemptionStatusById
Retries
Read-only; exact retries are safe

When to use this

  • An order shows a statusID you don't recognise, and you want its name and category.
  • Check that a status is still switched on before you move orders to it.
  • Confirm whether a status is in the refunded category before you send a coin refund.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getRedemptionStatusByIdShown in the dashboard as “Get Redemption Status By ID”

Use a Community API key with getRedemptionStatusById, and keep it on your server. This permission is separate from getRedemptionStatuses, which List redemption statuses needs. The key decides the community. The body must still name that same community in communityId; any other ID is rejected with 403.

Behaviour#

Only active statuses are returned. A status your team has switched off in the dashboard returns 404, the same as an ID that doesn't exist, and orders can't be moved to it.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with getRedemptionStatusById.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send both id and communityId as JSON strings. If you don't have your community ID yet, read serverId from any order in the order lists. Other fields are ignored.

id#stringREQUIRED
The status ID, from List redemption statuses or the statusID on an order.

Rule24-character hex ID

Eg"66f000000000000000000402"

communityId#stringREQUIRED
The ID of the community your API key belongs to. It is the serverId on every order.

Rule24-character community ID; must match your key

Eg"66f000000000000000000010"

curl --request POST \
  --url https://api.returning.ai/v1/redemption-transactions/status/detail \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "66f000000000000000000402",
    "communityId": "66f000000000000000000010"
  }'

Response#

A 200 returns the status in data, with the same fields as each entry in List redemption statuses.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_STATUS_RETRIEVED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Redemption status fetched successfully"

data#objectALWAYS
The status.

Eg{ ... }

_id#stringALWAYS
Status ID. Send it as statusID to Update redemption order status.

Eg"66f000000000000000000402"

name#stringALWAYS
Status name, such as Refunded. Orders show it as their status.

Eg"Refunded"

category#stringALWAYS
The status category.

Rulenew_purchase, in_progress, completed or refunded

Eg"refunded"

color#stringALWAYS
Display colour, a hex code such as #EB5757.

Eg"#EB5757"

order#numberALWAYS
Sort position within its category. Lower numbers come first.

Eg0

isDefault#booleanALWAYS
true for the category's default status.

Egtrue

{
  "status": "success",
  "code": "REDEMPTION_STATUS_RETRIEVED",
  "message": "Redemption status fetched successfully",
  "data": {
    "_id": "66f000000000000000000402",
    "name": "Refunded",
    "category": "refunded",
    "color": "#EB5757",
    "order": 0,
    "isDefault": true
  }
}

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. Branch on the HTTP status and code, never on message.

Fix the request04

400VALIDATION_FAILEDFix the request
id or communityId is missing, isn't a string, or isn't a 24-character ID. A missing or non-string value has detail naming the field; a bad format has message: Invalid status ID format or Invalid community ID format.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
The key lacks getRedemptionStatusById, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys.
403API_KEY_COMMUNITY_MISMATCHFix the request
communityId isn't the community your key belongs to, so nothing was read. Send your own community ID.

Fix the data02

404REDEMPTION_STATUS_NOT_FOUNDFix the data
No active status with this ID in your community. It may be switched off, deleted, or belong to another community. Get current IDs from List redemption statuses.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff02

500INTERNAL_ERRORRetry with backoff
The status could not be read. Retry the same request with exponential backoff.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing was read.
{
  "status": "fail",
  "code": "VALIDATION_FAILED",
  "message": "Invalid status ID format"
}

Next step#

Update redemption order statusPUT/v1/redemption-transactions/statusMove an order to this status, sending its _id as statusID.