Returning.AIDevelopers
v1

API reference / Store / Redemption-transaction

.md

Get redemption transaction detail

Read one redemption order in your community by its order ID, with its status, the trader's details and their order-form answers.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v2/redemption-transactions/{redemptionID}
Permission
customerSuccess
Retries
Read-only; exact retries are safe

When to use this

  • A trader quotes an order ID (ORD...) and you need the order's current status and details.
  • Confirm an order after you change its status, voucher or customer details.
  • Show one order's details in your own support tool without paging through a list.

Authentication#

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

Send a Community API key with the customerSuccess permission. The key decides the community, so you can only read orders in that community. Keep the key on your server.

Request#

Path parameters#

redemptionID#stringREQUIRED
The order ID (ORD...), the redemptionId in the order lists. The internal _id isn't accepted.

RuleStarts with ORD

EgORD20269268300418273

Headers#

Authorization#stringREQUIRED
Community API key with customerSuccess.

RuleBearer <API_KEY>

curl --request GET \
  --url https://api.returning.ai/v2/redemption-transactions/ORD20269268300418273 \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the order in data. status is the status name and statusID its ID; match the ID against List redemption statuses. Fields such as rewardId, productName, userInfo, redemptionMethodName and customFieldValues are left out, not sent as null, when there is nothing to show. An order for a product that was later deleted still returns, without rewardId and productName.

Unlike the order lists, customFieldValues here is keyed by the form field's name, not its ID. Branch on the HTTP status and meta.code, never on message.

meta#objectALWAYS
Status details.

Eg{ ... }

status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.

Eg200

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_TRANSACTION_RETRIEVED

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

Eg"Redemption transaction fetched successfully"

data#objectALWAYS
The order.

Eg{ ... }

_id#stringALWAYS
Internal record ID of the order. Other redemption endpoints take redemptionId.

Eg"66f000000000000000000401"

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

Eg"ORD20269268300418273"

serverId#stringALWAYS
Your community ID.

Eg"66f000000000000000000010"

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

Eg"<userObjectId>"

rewardId#stringWHEN FOUND
ID of the store product that was redeemed. Left out when the product can't be found, for example after it was deleted.

Eg"66f000000000000000000101"

voucherId#stringWHEN SET
ID of the voucher assigned to the order.

Eg"66f000000000000000000502"

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

Eg500

quantity#integerALWAYS
Units in the order.

Eg1

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

Eg"Completed"

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

Eg"66f000000000000000000405"

type#stringALWAYS
The reward type.

Rulevoucher

userInfo#objectWHEN SET
Contact and delivery details saved on the order. Left out when there are none.

Eg{ ... }

username#stringWHEN SET
The trader's username.

Eg"sample_trader"

name#stringWHEN SET
The trader's display name.

Eg"Sample Trader"

email#stringWHEN SET
The trader's email.

Eg"trader@example.com"

profile#stringWHEN SET
The trader's avatar URL.
firstName#stringWHEN SET
First name, when the trader entered one or you set it.
lastName#stringWHEN SET
Last name, when the trader entered one or you set it.
redemptionMethodName#stringWHEN SET
How the trader chose to receive the reward. Older orders show Custom Instructions or Physical Delivery. Left out when the order has none.

Eg"Custom Instructions"

customFieldValues#objectWHEN SET
Answers to the product's order form, keyed by field name, such as {"Account number": "<brokerCustomerId>"}. A repeated name gets a suffix, such as Account number (2). Left out when the order has no answers.

Eg{"Account number": "<brokerCustomerId>"}

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

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

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

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

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

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

productName#stringWHEN FOUND
The product's name. Left out when the product can't be found, for example after it was deleted.

Eg"$25 Trading Credit"

userData#objectALWAYS
The trader's account details.

Eg{ ... }

email#stringALWAYS
The trader's email.

Eg"trader@example.com"

userName#stringALWAYS
The trader's username.

Eg"sample_trader"

roles#string[]ALWAYS
Names of the trader's roles in your community.

Eg["@all"]

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "REDEMPTION_TRANSACTION_RETRIEVED"
  },
  "message": "Redemption transaction fetched successfully",
  "data": {
    "_id": "66f000000000000000000401",
    "redemptionId": "ORD20269268300418273",
    "serverId": "66f000000000000000000010",
    "userId": "<userObjectId>",
    "rewardId": "66f000000000000000000101",
    "voucherId": "66f000000000000000000502",
    "price": 500,
    "quantity": 1,
    "status": "Completed",
    "statusID": "66f000000000000000000405",
    "type": "voucher",
    "userInfo": {
      "username": "sample_trader",
      "name": "Sample Trader",
      "email": "trader@example.com"
    },
    "redemptionMethodName": "Custom Instructions",
    "customFieldValues": {
      "Account number": "<brokerCustomerId>"
    },
    "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"]
    }
  }
}

Errors#

Every error carries its code in meta.code, with the reason in detail. An order in another community returns 404, the same as a missing one. The message on a 400 doesn't describe this endpoint, so don't read it.

Fix the request04

400VALIDATION_FAILEDFix the request
redemptionID doesn't start with ORD. Send the order ID from redemptionId, not the internal _id.
401AUTH_API_KEY_REQUIREDFix the request
No key was sent. Send Authorization: Bearer <API_KEY>.
401AUTH_API_KEY_INVALIDFix the request
The key is unknown, expired or malformed. Use a current Community API key.
403AUTH_PERMISSION_REQUIREDFix the request
The key lacks customerSuccess. Add the permission in Settings > Integration > API Keys.

Fix the data01

404REDEMPTION_TRANSACTION_NOT_FOUNDFix the data
No order with this ID in your community. Check the ID against the order lists; order IDs are matched exactly.

Retry with backoff03

502REDEMPTION_DEPENDENCY_UNAVAILABLERetry with backoff
Orders are briefly unavailable. Retry the same request with exponential backoff.
500INTERNAL_ERRORRetry with backoff
Retry the same request with exponential backoff. If it keeps failing, contact Returning.AI with the time of the request.
401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff
The key could not be checked just now. Retry with backoff; the key itself may be fine.
{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Read community member param validation error",
  "detail": {
    "redemptionID": "redemptionID must be a public order ID beginning with ORD"
  },
  "solution": "Please check the request and try again"
}

Next step#

Get redemption order status historyPOST/v1/redemption-transactions/transaction-historySee how the order reached its current status, with each change and its remark.