Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

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.

Last updated 26 Sep 2026API v1

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

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.

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

Authorization#stringREQUIRED
Community API key with customerSuccess.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

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

identifier#objectREQUIRED
The custom user field and value that identify the trader.

Eg{"key": "customerid", "value": "<brokerCustomerId>"}

key#stringREQUIRED
Key of a custom single-line text or numerical user field, usually your broker identifier such as customerid. Case-sensitive.

RuleCustom field key; not id or email

Eg"customerid"

value#string | numberREQUIRED
The trader's value in that field. Matched exactly, ignoring leading and trailing spaces.

RuleNon-empty string, or a number

Eg"<brokerCustomerId>"

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

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.

Eg[ ... ]

_id#string
Internal record ID of the order. Other redemption endpoints take redemptionId, not this.

Eg"66f000000000000000000401"

redemptionId#string
The order ID (ORD...). Send it as transactionId to update the order or read its history.

Eg"ORD20269268300418273"

serverId#string
Your community ID.

Eg"66f000000000000000000010"

userId#string
The trader's internal record ID. This is not the platform user ID.

Eg"<userObjectId>"

rewardId#string
ID of the store product that was redeemed.

Eg"66f000000000000000000101"

voucherId#string
ID of the voucher assigned to the order.

Eg"66f000000000000000000502"

price#number
Coins the trader paid for the order. A coin refund returns this amount.

RuleMin 0

Eg500

quantity#number
Units in the order.

RuleMin 0

Eg1

status#string
The order's current status name, such as New Purchase or Refunded.

Eg"Refunded"

statusID#string
ID of the order's current status. Present when the order has one.

Eg"66f000000000000000000402"

type#string
The product type, such as voucher.

Eg"voucher"

userInfo#object
Contact and delivery details for the order. The trader's username, name and email, plus any delivery address they entered.

Eg{ ... }

redemptionOptionType#string
How the reward is delivered, customInstructions or physicalDelivery, when the product sets one.

RuleNullable

Eg"digital"

redemptionMethodID#string
ID of the redemption method the trader chose. Older orders don't have one.

Eg"method-synthetic-001"

redemptionMethodName#string
Name of that redemption method, as it was when the trader redeemed.

Eg"Email delivery"

customFieldValues#object
Answers to the product's order form, keyed by form field ID, when the product has one.

RuleNullable

Eg{"client_id": "synthetic-client-id"}

purchasedDate#string
When the trader redeemed, ISO 8601 UTC.

RuleDate-time

Eg"2026-09-26T08:30:00.000Z"

createdAt#string
When the order was created, ISO 8601 UTC.

RuleDate-time

Eg"2026-09-26T08:30:00.000Z"

updatedAt#string
When the order last changed, ISO 8601 UTC.

RuleDate-time

Eg"2026-09-26T09:15:00.000Z"

productName#string
The product name as it was when the trader redeemed. null if unknown.

RuleNullable

Eg"$25 Trading Credit"

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.

RuleMin 0

Eg1

page#integerALWAYS
The page you asked for.

RuleMin 1

Eg1

limit#integerALWAYS
The page size used.

Rule1-100

Eg20

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

RuleMin 0

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 request06

400VALIDATION_FAILEDFix the request
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.
400CUSTOM_FIELD_IDENTIFIER_NOT_FOUNDFix the request
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.
400CUSTOM_FIELD_IDENTIFIER_UNSUPPORTED_TYPEFix the request
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.
400CUSTOM_FIELD_IDENTIFIER_INVALID_VALUEFix the request
The value is blank, or isn't a number for a numerical field. Correct it and retry.
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 data04

404USER_NOT_FOUNDFix the data
No active trader in your community has this value in that field. Check the value, or look the trader up by email.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.
409CUSTOM_FIELD_IDENTIFIER_DUPLICATEFix the data
More than one active trader has this value, so no orders were returned. Look the trader up by email, and fix the duplicate values.
409CUSTOM_FIELD_IDENTIFIER_LOOKUP_AMBIGUOUSFix the data
Too many records hold this value to prove it belongs to one trader. Look the trader up by email instead.

Retry with backoff04

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.
503CUSTOM_FIELD_IDENTIFIER_NOT_READYRetry with backoff
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.
503CUSTOM_FIELD_IDENTIFIER_SCAN_LIMIT_EXCEEDEDRetry with backoff
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.
{
  "status": "fail",
  "code": "CUSTOM_FIELD_IDENTIFIER_NOT_FOUND",
  "message": "Custom field identifier does not exist."
}

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.