Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

Create redemption order status

Add a status to your community's redemption order workflow, in one of the four fixed categories.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/redemption-transactions/status
Permission
createRedemptionStatus
Retries
No Idempotency-Key; a repeat returns 409

When to use this

  • Your fulfilment has a step the default statuses don't cover, such as Awaiting Delivery.
  • You want separate refunded statuses for different reasons, such as out of stock or failed checks.
  • You set up a new community's order workflow before you start updating orders.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
createRedemptionStatusShown in the dashboard as “Create Redemption Status”

Use a Community API key with createRedemptionStatus, and keep it on your server. The key decides the community, so never send a communityId.

Behaviour#

The status is active as soon as you get a 201. It appears in List redemption statuses under its category, and you can move orders into it straight away. Its colour is #808080. It is never a category default, so new orders don't start in it unless a product or Store category is set to use it.

Names are unique across your community. The same name in any other category is rejected, matched exactly, and so is the same name with different capital letters in the same category. Statuses your team has switched off still count, even though the list doesn't show them.

The API can't change or remove a status. To recolour, rename, switch off or delete one, your team uses Settings > Store Management > Product Statuses in the dashboard. A status can't be deleted while it is the only one in its category. The dashboard only saves names of up to 50 characters, so a longer name created here blocks saving any change to that category there until it is shortened.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with createRedemptionStatus.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send name and category. Other fields, such as color or communityId, are ignored.

name#stringREQUIRED
Status name. Orders in this status show it as their status. Must be unique in your community. Keep it to 50 characters so your team can still edit this category in the dashboard.

Rule1-100 characters

Eg"Awaiting Delivery"

category#stringREQUIRED
The category the status belongs to. Only refunded statuses can return coins when you update an order.

Rulenew_purchase, in_progress, completed or refunded

Eg"in_progress"

curl --request POST \
  --url https://api.returning.ai/v1/redemption-transactions/status \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Awaiting Delivery",
    "category": "in_progress"
  }'

Response#

A 201 returns the new status in data. Save data._id: it is the statusID for Update redemption order status. Branch on the HTTP status and code, never on message.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_STATUS_CREATED

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

Eg"Redemption status created successfully"

data#objectALWAYS
The new status.

Eg{ ... }

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

Eg"66f000000000000000000406"

name#stringALWAYS
The stored name.

Eg"Awaiting Delivery"

category#stringALWAYS
The status category.

Eg"in_progress"

color#stringALWAYS
Display colour. Always #808080 for a status created here.

Eg"#808080"

order#numberALWAYS
Sort position. One more than the highest in your community, so the new status is listed last in its category.

Eg1

isDefault#booleanALWAYS
Always false. A created status is never a category's default.
{
  "status": "success",
  "code": "REDEMPTION_STATUS_CREATED",
  "message": "Redemption status created successfully",
  "data": {
    "_id": "66f000000000000000000406",
    "name": "Awaiting Delivery",
    "category": "in_progress",
    "color": "#808080",
    "order": 1,
    "isDefault": 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. No 400 or 409 creates a status.

Fix the request03

400VALIDATION_FAILEDFix the request
name is missing, empty or over 100 characters, or category isn't one of the four categories. detail names the field. Nothing was created.
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 createRedemptionStatus, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys.

Fix the data02

409REDEMPTION_STATUS_CONFLICTFix the data
Your community already has a status with this name: the exact name in any category, or the same name with different capital letters in this category. Switched-off statuses count too. message names the category you sent, even when the existing status is in another one. Use the existing status, or choose another name.
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 outcome is unknown. List redemption statuses and look for the name in its category; create again only if it isn't there.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked, and nothing was created. Retry with backoff.
{
  "status": "fail",
  "code": "VALIDATION_FAILED",
  "message": "Create redemption status endpoint",
  "detail": {
    "category": "Category must be one of: new_purchase, in_progress, completed, refunded"
  }
}

Next step#

Update redemption order statusPUT/v1/redemption-transactions/statusMove an order into the new status, sending its _id as statusID.