# 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.

- Endpoint: `POST https://api.returning.ai/v1/redemption-transactions/statuses`
- Section: Store and rewards / Rewards and redemptions
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `getRedemptionStatuses` (Shown in the dashboard as "Get Redemption Statuses")
- Retries: Read-only; exact retries are safe
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-statuses

## 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.

**Instead:** Use [Get redemption status by ID](https://docs.returning.ai/api-reference/rewards-and-redemptions/get-redemption-status-by-id.md) instead to check one status you already have the ID for. It needs its own permission, `getRedemptionStatusById`.

**Community ID:** The body must carry your own community ID. Any other ID returns `403 API_KEY_COMMUNITY_MISMATCH`, and a missing one returns `400`.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `getRedemptionStatuses`

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `getRedemptionStatuses`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/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.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `communityId` | `string` | Yes | The ID of the community your API key belongs to. It is the `serverId` on every order in the order lists. (24-character community ID; must match your key) |

### Example request

```bash
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.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `code` | `string` | always | Machine-readable result code. (`REDEMPTION_STATUSES_RETRIEVED`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | Your active statuses, one list per category. A category with no active status is left out. |
| `data.new_purchase` | `object[]` | when not empty | Statuses for orders that were just placed, sorted by `order`. |
| `data.new_purchase._id` | `string` | always | Status ID. Send it as `statusID` to Update redemption order status. |
| `data.new_purchase.name` | `string` | always | Status name, such as `New Purchase`. Orders show it as their `status`. |
| `data.new_purchase.category` | `string` | always | The status category, the same as the list it is in. (`new_purchase`, `in_progress`, `completed` or `refunded`) |
| `data.new_purchase.color` | `string` | always | Display colour, a hex code such as `#FF9C00`. |
| `data.new_purchase.order` | `number` | always | Sort position. Lower numbers come first. |
| `data.new_purchase.isDefault` | `boolean` | always | `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. |
| `data.in_progress` | `object[]` | when not empty | Statuses for orders your team is working on. Same fields as `new_purchase`. |
| `data.completed` | `object[]` | when not empty | Statuses for fulfilled orders. Same fields as `new_purchase`. |
| `data.refunded` | `object[]` | when not empty | Statuses for refunded orders. Only these can return coins with Update redemption order status. Same fields as `new_purchase`. |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | `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. |
| 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer <API_KEY>` with a current Community API key. |
| 403 | `API_KEY_PERMISSION_DENIED` | The key lacks `getRedemptionStatuses`, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys. |
| 403 | `API_KEY_COMMUNITY_MISMATCH` | `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 data

| Status | Code | What to do |
| --- | --- | --- |
| 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 statuses could not be read. Retry the same request with exponential backoff. |
| 500 | `AUTHENTICATION_FAILED` | The key could not be checked. Retry with backoff; nothing was read. |

**Retries:** This endpoint is read-only, so retrying the exact same request is safe after a network error or a 5xx. Use bounded exponential backoff. 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 to one of these statuses, sending the status `_id` as `statusID`.
- [Need another status? Create redemption order status](https://docs.returning.ai/api-reference/rewards-and-redemptions/create-redemption-order-status.md): `POST /v1/redemption-transactions/status`.