# Create redemption order status Add a status to your community's redemption order workflow, in one of the four fixed categories. - Endpoint: `POST https://api.returning.ai/v1/redemption-transactions/status` - Section: Store and rewards / Rewards and redemptions - Authentication: `Authorization: Bearer ` (Community API key) - Permission: `createRedemptionStatus` (Shown in the dashboard as "Create Redemption Status") - Retries: No Idempotency-Key; a repeat returns 409 - Guide: hand-written - Verified: live, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/rewards-and-redemptions/create-redemption-order-status ## 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. **Instead:** Use [List redemption statuses](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-statuses.md) instead to find a status that may already exist. **No undo through the API:** The API can't rename, switch off or delete a status. Your team can only do that in the dashboard, so create the statuses you mean to keep. ## Authentication - Header: `Authorization: Bearer ` - Permission: `createRedemptionStatus` 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 | Name | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | Yes | Community API key with `createRedemptionStatus`. (`Bearer `) | | `Content-Type` | `string` | Yes | Request body format. (`application/json`) | ### Body Send `name` and `category`. Other fields, such as `color` or `communityId`, are ignored. | Name | Type | Required | Description | | --- | --- | --- | --- | | `name` | `string` | Yes | 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. (1-100 characters) | | `category` | `string` | Yes | The category the status belongs to. Only `refunded` statuses can return coins when you update an order. (`new_purchase`, `in_progress`, `completed` or `refunded`) | ### Example request ```bash curl --request POST \ --url https://api.returning.ai/v1/redemption-transactions/status \ --header 'Authorization: Bearer ' \ --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`. ### Response fields | Field | Type | Presence | Description | | --- | --- | --- | --- | | `status` | `string` | always | Result of the request. (`success`) | | `code` | `string` | always | Machine-readable result code. (`REDEMPTION_STATUS_CREATED`) | | `message` | `string` | always | Human-readable summary. Do not branch on it. | | `data` | `object` | always | The new status. | | `data._id` | `string` | always | Status ID. Send it as `statusID` to Update redemption order status. | | `data.name` | `string` | always | The stored name. | | `data.category` | `string` | always | The status category. | | `data.color` | `string` | always | Display colour. Always `#808080` for a status created here. | | `data.order` | `number` | always | Sort position. One more than the highest in your community, so the new status is listed last in its category. | | `data.isDefault` | `boolean` | always | Always `false`. A created status is never a category's default. | ### Example response (201) ```json { "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 request | Status | Code | What to do | | --- | --- | --- | | 400 | `VALIDATION_FAILED` | `name` is missing, empty or over 100 characters, or `category` isn't one of the four categories. `detail` names the field. Nothing was created. | | 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer ` with a current Community API key. | | 403 | `API_KEY_PERMISSION_DENIED` | 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 data | Status | Code | What to do | | --- | --- | --- | | 409 | `REDEMPTION_STATUS_CONFLICT` | 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. | | 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. | ### Retry with backoff | Status | Code | What to do | | --- | --- | --- | | 500 | `INTERNAL_ERROR` | The outcome is unknown. List redemption statuses and look for the name in its category; create again only if it isn't there. | | 500 | `AUTHENTICATION_FAILED` | The key could not be checked, and nothing was created. Retry with backoff. | **Retries:** This endpoint doesn't accept an `Idempotency-Key`. Because names are unique, repeating a create that already succeeded returns `409` instead of a second status. After a timeout or a `500`, list redemption statuses and look for the name before you send it again. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry. ## Next step - [Update redemption order status](https://docs.returning.ai/api-reference/rewards-and-redemptions/update-redemption-order-status.md): `PUT /v1/redemption-transactions/status`. Move an order into the new status, sending its `_id` as `statusID`. - [Confirm it with List redemption statuses](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-statuses.md): `POST /v1/redemption-transactions/statuses`.