Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

List redemption statuses

List every active redemption order status in your community, grouped by category, with the IDs you send as statusID when you update an order.

Last updated 26 Sep 2026API v1

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

When to use this

  • Find the statusID to send when you move an order to another status.
  • Map the statusID on each order to a status name and colour in your own system.
  • Check whether a status already exists before you create one.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getRedemptionStatusesShown in the dashboard as “Get Redemption Statuses”

Use a Community API key with getRedemptionStatuses, and keep it on your server. 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 listed. A status your team has switched off in the dashboard is left out, and orders can't be moved to it. The categories are fixed: new_purchase, in_progress, completed and refunded. Each category has a default status, created as New Purchase, In Progress, Completed and Refunded, which your team can rename or switch off.

A category with no active status is left out of data, not returned as an empty list, so check that a key exists before you read it. Statuses you create are added after the existing ones. The whole list comes back in one response, with no paging.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with getRedemptionStatuses.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send communityId as a JSON string. If you don't have it yet, read serverId from any order in List redemption orders by community. Other fields are ignored.

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

Rule24-character community ID; must match your key

Eg"66f000000000000000000010"

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

Response#

A 200 returns the statuses in data, one list per category. Use _id as statusID when you update an order, and match it against statusID on the orders you read.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_STATUSES_RETRIEVED

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

Eg"Redemption statuses fetched successfully"

data#objectALWAYS
Your active statuses, one list per category. A category with no active status is left out.

Eg{ ... }

new_purchase#object[]WHEN NOT EMPTY
Statuses for orders that were just placed, sorted by order.

Eg[ ... ]

_id#stringALWAYS
Status ID. Send it as statusID to Update redemption order status.
name#stringALWAYS
Status name, such as New Purchase. Orders show it as their status.
category#stringALWAYS
The status category, the same as the list it is in.

Rulenew_purchase, in_progress, completed or refunded

color#stringALWAYS
Display colour, a hex code such as #FF9C00.
order#numberALWAYS
Sort position. Lower numbers come first.
isDefault#booleanALWAYS
true for the category's default status. New orders start in the default new_purchase status unless the product or its Store category sets another.
in_progress#object[]WHEN NOT EMPTY
Statuses for orders your team is working on. Same fields as new_purchase.

Eg[ ... ]

completed#object[]WHEN NOT EMPTY
Statuses for fulfilled orders. Same fields as new_purchase.

Eg[ ... ]

refunded#object[]WHEN NOT EMPTY
Statuses for refunded orders. Only these can return coins with Update redemption order status. Same fields as new_purchase.

Eg[ ... ]

{
  "status": "success",
  "code": "REDEMPTION_STATUSES_RETRIEVED",
  "message": "Redemption statuses fetched successfully",
  "data": {
    "new_purchase": [
      {
        "_id": "66f000000000000000000403",
        "name": "New Purchase",
        "category": "new_purchase",
        "color": "#FF9C00",
        "order": 0,
        "isDefault": true
      }
    ],
    "in_progress": [
      {
        "_id": "66f000000000000000000404",
        "name": "In Progress",
        "category": "in_progress",
        "color": "#2F80ED",
        "order": 0,
        "isDefault": true
      },
      {
        "_id": "66f000000000000000000406",
        "name": "Awaiting Delivery",
        "category": "in_progress",
        "color": "#808080",
        "order": 1,
        "isDefault": false
      }
    ],
    "completed": [
      {
        "_id": "66f000000000000000000405",
        "name": "Completed",
        "category": "completed",
        "color": "#27AE60",
        "order": 0,
        "isDefault": true
      }
    ],
    "refunded": [
      {
        "_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
communityId is missing, isn't a string, or isn't a 24-character ID. A missing or non-string value has detail.communityId; a bad format has message: Invalid community ID format. Send your community ID as a JSON string.
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 getRedemptionStatuses, 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, or use the other community's key.

Fix the data01

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 statuses 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 community ID format"
}

Next step#

Update redemption order statusPUT/v1/redemption-transactions/statusMove an order to one of these statuses, sending the status _id as statusID.