# List redemption orders by community

List every redemption order in your community, newest first, one page at a time.

- Endpoint: `POST https://api.returning.ai/v1/redemption-transactions/by-community`
- Section: Store and rewards / Rewards and redemptions
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `customerSuccess` (Shown in the dashboard as "Customer Success")
- 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-orders-by-community

## When to use this

- Sync new store orders into your fulfilment or back-office system.
- Build a support queue of orders by status, such as everything still in `New Purchase`.
- Find an order ID (`ORD...`) before you change its status or read its status history.

**Instead:** Use [List redemption orders by custom-field identifier](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-orders-by-custom-field-identifier.md) instead to list one trader's orders.

## Authentication

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

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

## Behaviour

Orders come back newest first, by redemption time. The list has no filters: every order in your community is included, whatever its status, and any other body field is ignored. To track new orders, read from page 1 until you reach an order you already have. Orders redeemed while you page push older ones down, so the same order can appear on two pages; de-duplicate by `redemptionId`.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `customerSuccess`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

Both fields are optional. `limit` defaults to 10 and can be at most 100. A page past the last one returns an empty `transactions` list with the real `total`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Page number, starting at 1. (Whole number, 1 or more; default 1) |
| `limit` | `integer` | No | Orders per page. Omit to use 10. (Default 10; max 100) |

### Example request

```bash
curl --request POST \
  --url https://api.returning.ai/v1/redemption-transactions/by-community \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "limit": 20
  }'
```

## Response

A `200` returns the page in `data.transactions` and the totals in `data.pagination`. Each order has two IDs. `redemptionId` is the order ID (`ORD...`) that every other redemption endpoint takes as `transactionId`. `_id` is an internal record ID; don't send it anywhere. Map `statusID` to your own status labels with [List redemption statuses](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-statuses.md).

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The page of orders and the paging totals. |
| `data.transactions` | `object[]` | always | Orders on this page, newest purchase first. Empty when there are none. |
| `data.transactions._id` | `string` | - | Internal record ID of the order. Other redemption endpoints take `redemptionId`, not this. |
| `data.transactions.redemptionId` | `string` | - | The order ID (`ORD...`). Send it as `transactionId` to update the order or read its history. |
| `data.transactions.serverId` | `string` | - | Your community ID. |
| `data.transactions.userId` | `string` | - | The trader's internal record ID. This is not the platform user ID. |
| `data.transactions.rewardId` | `string` | - | ID of the store product that was redeemed. |
| `data.transactions.voucherId` | `string` | - | ID of the voucher assigned to the order. |
| `data.transactions.price` | `number` | - | Coins the trader paid for the order. A coin refund returns this amount. |
| `data.transactions.quantity` | `number` | - | Units in the order. |
| `data.transactions.status` | `string` | - | The order's current status name, such as `New Purchase` or `Refunded`. |
| `data.transactions.statusID` | `string` | - | ID of the order's current status. Present when the order has one. |
| `data.transactions.type` | `string` | - | The product type, such as `voucher`. |
| `data.transactions.userInfo` | `object` | - | Contact and delivery details for the order. The trader's username, name and email, plus any delivery address they entered. |
| `data.transactions.redemptionOptionType` | `string` | - | How the reward is delivered, `customInstructions` or `physicalDelivery`, when the product sets one. |
| `data.transactions.customFieldValues` | `object` | - | Answers to the product's order form, keyed by form field ID, when the product has one. |
| `data.transactions.purchasedDate` | `string` | - | When the trader redeemed, ISO 8601 UTC. |
| `data.transactions.createdAt` | `string` | - | When the order was created, ISO 8601 UTC. |
| `data.transactions.updatedAt` | `string` | - | When the order last changed, ISO 8601 UTC. |
| `data.transactions.productName` | `string` | - | The product name as it was when the trader redeemed. `null` if unknown. |
| `data.transactions.userData` | `object` | - | The trader's account details. |
| `data.transactions.userData.email` | `string` | - | The trader's email. `null` if the trader can't be matched. |
| `data.transactions.userData.userName` | `string` | - | The trader's username. `null` if the trader can't be matched. |
| `data.transactions.userData.roles` | `string[]` | - | Names of the trader's roles in your community. |
| `data.pagination` | `object` | always | Paging totals for the whole list. |
| `data.pagination.total` | `integer` | always | Orders in your community across all pages. |
| `data.pagination.page` | `integer` | always | The page you asked for. |
| `data.pagination.limit` | `integer` | always | The page size used. |
| `data.pagination.totalPages` | `integer` | always | Pages at this `limit`. `0` when there are no orders. |
| `code` | `string` | always | Machine-readable result code. (`REDEMPTION_TRANSACTIONS_RETRIEVED`) |

### Example response (200)

```json
{
  "status": "success",
  "code": "REDEMPTION_TRANSACTIONS_RETRIEVED",
  "message": "Redemption transactions fetched successfully",
  "data": {
    "transactions": [
      {
        "_id": "66f000000000000000000401",
        "redemptionId": "ORD20269268300418273",
        "serverId": "66f000000000000000000010",
        "userId": "<userObjectId>",
        "rewardId": "66f000000000000000000101",
        "voucherId": "66f000000000000000000502",
        "price": 500,
        "quantity": 1,
        "status": "Refunded",
        "statusID": "66f000000000000000000402",
        "type": "voucher",
        "userInfo": {
          "username": "sample_trader",
          "name": "Sample Trader",
          "email": "trader@example.com"
        },
        "purchasedDate": "2026-09-26T08:30:00.000Z",
        "createdAt": "2026-09-26T08:30:00.000Z",
        "updatedAt": "2026-09-26T09:15:00.000Z",
        "productName": "$25 Trading Credit",
        "userData": {
          "email": "trader@example.com",
          "userName": "sample_trader",
          "roles": ["@all"]
        }
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 20,
      "totalPages": 1
    }
  }
}
```

## 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` | `page` or `limit` is not a whole number in range. `detail` names the field. Send `page` of 1 or more and `limit` from 1 to 100. |
| 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 `customerSuccess`, 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 |
| --- | --- | --- |
| 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 order list 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 its next status, or refund it, using the order's `redemptionId`.
- [See how an order got there with Get redemption order status history](https://docs.returning.ai/api-reference/rewards-and-redemptions/get-redemption-order-status-history.md): `POST /v1/redemption-transactions/transaction-history`.