# List redemption orders by user email List one trader's redemption orders in your community, newest first, finding the trader by their email. - Endpoint: `POST https://api.returning.ai/v1/redemption-transactions/by-email` - Section: Store and rewards / Rewards and redemptions - Authentication: `Authorization: Bearer ` (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-user-email ## When to use this - A trader contacts support with their email and asks where their reward is. - Show a trader's reward orders inside your own client portal, where you know their email. - Find an order ID (`ORD...`) for one trader before you change its status or read its 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 when you only have your broker customer ID. ## Authentication - Header: `Authorization: Bearer ` - 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`; it is ignored. Only orders in that community are returned. ## Behaviour The email is matched ignoring capital letters, against every Returning.AI account, including deleted ones. An account that exists but has no orders in your community returns `200` with an empty list, not `404`. A `404` means no account has this email at all. 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 `) | | `Content-Type` | `string` | Yes | Request body format. (`application/json`) | ### Body `email` is required. `page` and `limit` are optional; `limit` defaults to 10 and can be at most 100. Numbers sent as strings, such as `"20"`, are accepted. Other fields are ignored. | Name | Type | Required | Description | | --- | --- | --- | --- | | `email` | `string` | Yes | The trader's email. Capital letters don't matter. (A valid email address) | | `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-email \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "email": "trader@example.com", "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 page past the last one returns an empty list with the real `total`. `redemptionId` is the order ID (`ORD...`) that every other redemption endpoint takes. When a product has been deleted, its orders stay in the list, without `rewardId` or `type`, and with `productName` as `null`. ### 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 in your community. | | `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. Left out when the product no longer exists. | | `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`. Left out when the product no longer exists. | | `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.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. | | `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.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. | | `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 the trader has no orders. | ### Example response (200) ```json { "status": "success", "code": "REDEMPTION_TRANSACTIONS_RETRIEVED", "message": "Redemption transactions fetched successfully", "data": { "transactions": [ { "_id": "66f000000000000000000401", "redemptionId": "ORD20269268300418273", "serverId": "66f000000000000000000010", "userId": "", "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` | `email` is missing or isn't a valid email, or `page` or `limit` is out of range. `detail` names the field, for example `Invalid email format` or `Number must be less than or equal to 100`. | | 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 `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 Returning.AI account has this email. Check the spelling, or look the trader up by your broker customer ID instead. | | 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 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. | **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`. - [Open one order with Get redemption transaction detail](https://docs.returning.ai/api-reference/store-redemption-transaction/get-redemption-transaction-detail.md): `GET /v2/redemption-transactions/{redemptionID}`.