# List redemption orders by custom-field identifier

List one trader's redemption orders in your community, newest first, finding the trader by a custom user field such as your broker customer ID.

- Endpoint: `POST https://api.returning.ai/v1/redemption-transactions/by-identifier`
- 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-custom-field-identifier

## When to use this

- A trader contacts support and you only have their broker customer ID.
- Show a trader's reward orders inside your own client portal.
- Find an order ID (`ORD...`) for one trader before you change its status or read its history.

**Instead:** Use [List redemption orders by user email](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-orders-by-user-email.md) instead when you have the trader's email.

## 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`. The lookup only finds traders in that community, and only their orders there.

## Behaviour

The identifier must match exactly one active trader in your community. Deleted accounts and removed members aren't matched, and return `404 USER_NOT_FOUND`. Text values are compared exactly, including capital letters, after leading and trailing spaces are removed. For a numerical field, `"10042"` and `10042` match the same trader.

Orders come back newest first, by redemption time, whatever their status. Orders the trader redeems while you page push older ones down, so 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

`identifier` is required, with both `key` and `value`. `page` and `limit` are optional; `limit` defaults to 10 and can be at most 100. To look a trader up by email, use List redemption orders by user email instead: `id` and `email` aren't accepted as keys here. Unknown fields are ignored.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `identifier` | `object` | Yes | The custom user field and value that identify the trader. |
| `identifier.key` | `string` | Yes | Key of a custom single-line text or numerical user field, usually your broker identifier such as `customerid`. Case-sensitive. (Custom field key; not `id` or `email`) |
| `identifier.value` | `string \| number` | Yes | The trader's value in that field. Matched exactly, ignoring leading and trailing spaces. (Non-empty string, or a number) |
| `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-identifier \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "identifier": {
      "key": "customerid",
      "value": "<brokerCustomerId>"
    },
    "page": 1,
    "limit": 20
  }'
```

## Response

A `200` returns the page in `data.transactions` and the totals in `data.pagination`, with the same order fields as List redemption orders by community plus the redemption method when the order has one, and without `userData`. A trader with no orders gets an empty list and `total` of `0`, not a `404`. `redemptionId` is the order ID (`ORD...`) that every other redemption endpoint takes as `transactionId`. Map `statusID` to your own status labels with List redemption statuses.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `code` | `string` | always | Machine-readable result code. (`REDEMPTION_TRANSACTIONS_RETRIEVED`) |
| `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 | The trader's orders on this page, newest purchase first. Empty when the trader has 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. (Min 0) |
| `data.transactions.quantity` | `number` | - | Units in the order. (Min 0) |
| `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. (Nullable) |
| `data.transactions.redemptionMethodID` | `string` | - | ID of the redemption method the trader chose. Older orders don't have one. |
| `data.transactions.redemptionMethodName` | `string` | - | Name of that redemption method, as it was when the trader redeemed. |
| `data.transactions.customFieldValues` | `object` | - | Answers to the product's order form, keyed by form field ID, when the product has one. (Nullable) |
| `data.transactions.purchasedDate` | `string` | - | When the trader redeemed, ISO 8601 UTC. (Date-time) |
| `data.transactions.createdAt` | `string` | - | When the order was created, ISO 8601 UTC. (Date-time) |
| `data.transactions.updatedAt` | `string` | - | When the order last changed, ISO 8601 UTC. (Date-time) |
| `data.transactions.productName` | `string` | - | The product name as it was when the trader redeemed. `null` if unknown. (Nullable) |
| `data.pagination` | `object` | always | Paging totals for this trader's orders. |
| `data.pagination.total` | `integer` | always | The trader's orders in your community across all pages. (Min 0) |
| `data.pagination.page` | `integer` | always | The page you asked for. (Min 1) |
| `data.pagination.limit` | `integer` | always | The page size used. (1-100) |
| `data.pagination.totalPages` | `integer` | always | Pages at this `limit`. `0` when the trader has no orders. (Min 0) |

### 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"
      }
    ],
    "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` | `identifier` is missing, `identifier.key` is empty, `id` or `email`, `identifier.value` is empty or not a string or number, or `page` or `limit` is out of range. `detail` names the field. For `id` or `email`, use the email endpoint or Get User Data instead. |
| 400 | `CUSTOM_FIELD_IDENTIFIER_NOT_FOUND` | No custom user field has this key. Built-in fields such as `country` aren't accepted, and keys are case-sensitive. Check the key against List user field definitions. |
| 400 | `CUSTOM_FIELD_IDENTIFIER_UNSUPPORTED_TYPE` | The field isn't a single-line text or numerical field. Use a field of one of those types, or look the trader up by email. |
| 400 | `CUSTOM_FIELD_IDENTIFIER_INVALID_VALUE` | The value is blank, or isn't a number for a numerical field. Correct it and retry. |
| 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 | `USER_NOT_FOUND` | No active trader in your community has this value in that field. Check the value, or look the trader up by email. |
| 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. |
| 409 | `CUSTOM_FIELD_IDENTIFIER_DUPLICATE` | More than one active trader has this value, so no orders were returned. Look the trader up by email, and fix the duplicate values. |
| 409 | `CUSTOM_FIELD_IDENTIFIER_LOOKUP_AMBIGUOUS` | Too many records hold this value to prove it belongs to one trader. Look the trader up by email instead. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | `INTERNAL_ERROR` | The orders 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. |
| 503 | `CUSTOM_FIELD_IDENTIFIER_NOT_READY` | Lookup by this field isn't ready yet, which can happen soon after the field is set up. Retry later with backoff, or look the trader up by email. |
| 503 | `CUSTOM_FIELD_IDENTIFIER_SCAN_LIMIT_EXCEEDED` | Too many records hold this value for a safe lookup, and no single trader was found. Look the trader up by email instead; retrying is unlikely to help unless the data changes. |

**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 one of the trader's orders 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`.