Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

Get redemption order status history

Read every status change on one redemption order, oldest first, with who or what made each change.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/redemption-transactions/transaction-history
Permission
getRedemptionTransactionHistory
Retries
Read-only; exact retries are safe

When to use this

  • A trader asks what happened to a reward order and when.
  • Confirm that a status change or refund you sent was recorded.
  • Audit refunds by checking when an order entered a refunded status.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
getRedemptionTransactionHistoryShown in the dashboard as “Get Redemption Transaction History”

Use a Community API key with getRedemptionTransactionHistory, and keep it on your server. The key decides the community, so you only see orders in that community.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with getRedemptionTransactionHistory.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send a JSON body with the order ID (ORD...) as transactionId. This is the order's redemptionId from the order lists, not its internal _id.

transactionId#stringREQUIRED
The order ID (ORD...) from redemptionId in the order lists. Not the order's internal _id.

RuleString

Eg"ORD20269268300418273"

curl --request POST \
  --url https://api.returning.ai/v1/redemption-transactions/transaction-history \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactionId": "ORD20269268300418273"
  }'

Response#

A 200 returns the changes in data.changes, oldest first, so the last entry is the latest change. Placing an order doesn't add an entry, so a new order has an empty list. An order ID that matches nothing also returns 200 with an empty list, not 404; check the ID against the order list if you expected changes. oldStatus and newStatus are status categories, and the names are copies taken at the time, so renaming a status later doesn't change old entries.

status#stringALWAYS
Result of the request.

Rulesuccess

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_TRANSACTION_STATUS_HISTORY_RETRIEVED

message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
The order's status changes.
transactionId#stringALWAYS
The order ID you sent.
changes#object[]ALWAYS
One entry per status change, oldest first. Empty when the order has never changed status, or the ID matches no order.
oldStatus#string
Category of the status before the change, such as new_purchase. unknown when the order had no earlier status.
oldStatusName#string
Name of the status before the change, as it was at the time. Left out when the order had no earlier status.
newStatus#string
Category of the status after the change, such as refunded.
newStatusName#string
Name of the status after the change, as it was at the time.
remark#string
The note saved with the change. API changes sent without a remark show Updated by API; dashboard changes name the team member.
updatedAt#string
When the change was made, ISO 8601 UTC.
{
  "status": "success",
  "code": "REDEMPTION_TRANSACTION_STATUS_HISTORY_RETRIEVED",
  "message": "Transaction status history retrieved successfully",
  "data": {
    "transactionId": "ORD20269268300418273",
    "changes": [
      {
        "oldStatus": "new_purchase",
        "oldStatusName": "New Purchase",
        "newStatus": "refunded",
        "newStatusName": "Refunded",
        "remark": "Reward out of stock",
        "updatedAt": "2026-09-26T09:15:00.000Z"
      }
    ]
  }
}

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
transactionId is missing or isn't a string. Send it as a JSON string in a JSON body.
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 getRedemptionTransactionHistory, or it is a personal key. Use a Community API key and add the permission in Settings > Integration > API Keys.

Fix the data01

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 history 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 transaction status history endpoint",
  "detail": {
    "transactionId": "Transaction ID is required"
  }
}

Next step#

Update redemption order statusPUT/v1/redemption-transactions/statusMove the order to its next status, or refund it.