Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

List redemption orders by user email

List one trader's redemption orders in your community, newest first, finding the trader by their email.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/redemption-transactions/by-email
Permission
customerSuccess
Retries
Read-only; exact retries are safe

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.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
customerSuccessShown in the dashboard as “Customer Success”

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#

Authorization#stringREQUIRED
Community API key with customerSuccess.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/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.

email#stringREQUIRED
The trader's email. Capital letters don't matter.

RuleA valid email address

Eg"trader@example.com"

page#integerOPTIONAL
Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg1

limit#integerOPTIONAL
Orders per page. Omit to use 10.

RuleDefault 10; max 100

Eg20

curl --request POST \
  --url https://api.returning.ai/v1/redemption-transactions/by-email \
  --header 'Authorization: Bearer <API_KEY>' \
  --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.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_TRANSACTIONS_RETRIEVED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Redemption transactions fetched successfully"

data#objectALWAYS
The page of orders and the paging totals.

Eg{ ... }

transactions#object[]ALWAYS
The trader's orders on this page, newest purchase first. Empty when the trader has none in your community.

Eg[ ... ]

_id#string
Internal record ID of the order. Other redemption endpoints take redemptionId, not this.
redemptionId#string
The order ID (ORD...). Send it as transactionId to update the order or read its history.
serverId#string
Your community ID.
userId#string
The trader's internal record ID. This is not the platform user ID.
rewardId#string
ID of the store product that was redeemed. Left out when the product no longer exists.
voucherId#string
ID of the voucher assigned to the order.
price#number
Coins the trader paid for the order. A coin refund returns this amount.
quantity#number
Units in the order.
status#string
The order's current status name, such as New Purchase or Refunded.
statusID#string
ID of the order's current status. Present when the order has one.
type#string
The product type, such as voucher. Left out when the product no longer exists.
userInfo#object
Contact and delivery details for the order. The trader's username, name and email, plus any delivery address they entered.
redemptionOptionType#string
How the reward is delivered, customInstructions or physicalDelivery, when the product sets one.
redemptionMethodID#string
ID of the redemption method the trader chose. Older orders don't have one.
redemptionMethodName#string
Name of that redemption method, as it was when the trader redeemed.
customFieldValues#object
Answers to the product's order form, keyed by form field ID, when the product has one.
purchasedDate#string
When the trader redeemed, ISO 8601 UTC.
createdAt#string
When the order was created, ISO 8601 UTC.
updatedAt#string
When the order last changed, ISO 8601 UTC.
productName#string
The product name as it was when the trader redeemed. null if unknown.
pagination#objectALWAYS
Paging totals for this trader's orders.

Eg{"total": 1, "page": 1, "limit": 20, "totalPages": 1}

total#integerALWAYS
The trader's orders in your community across all pages.

Eg1

page#integerALWAYS
The page you asked for.

Eg1

limit#integerALWAYS
The page size used.

Eg20

totalPages#integerALWAYS
Pages at this limit. 0 when the trader has no orders.

Eg1

{
  "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 request03

400VALIDATION_FAILEDFix the request
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.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
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 data02

404USER_NOT_FOUNDFix the data
No Returning.AI account has this email. Check the spelling, or look the trader up by your broker customer ID instead.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff02

500INTERNAL_ERRORRetry with backoff
The orders could not be read. Retry the same request with exponential backoff.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing was read.
{
  "status": "fail",
  "code": "VALIDATION_FAILED",
  "message": "Get redemption transactions by email endpoint",
  "detail": {
    "email": "Invalid email format"
  }
}

Next step#

Update redemption order statusPUT/v1/redemption-transactions/statusMove one of the trader's orders to its next status, or refund it, using the order's redemptionId.