# Get redemption order status history

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

- Endpoint: `POST https://api.returning.ai/v1/redemption-transactions/transaction-history`
- Section: Store and rewards / Rewards and redemptions
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `getRedemptionTransactionHistory` (Shown in the dashboard as "Get Redemption Transaction History")
- 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/get-redemption-order-status-history

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

**Instead:** Use [List redemption orders by community](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-orders-by-community.md) instead to see each order's current status.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `getRedemptionTransactionHistory`

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `getRedemptionTransactionHistory`. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/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`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionId` | `string` | Yes | The order ID (`ORD...`) from `redemptionId` in the order lists. Not the order's internal `_id`. (String) |

### Example request

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

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `code` | `string` | always | Machine-readable result code. (`REDEMPTION_TRANSACTION_STATUS_HISTORY_RETRIEVED`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The order's status changes. |
| `data.transactionId` | `string` | always | The order ID you sent. |
| `data.changes` | `object[]` | always | One entry per status change, oldest first. Empty when the order has never changed status, or the ID matches no order. |
| `data.changes.oldStatus` | `string` | - | Category of the status before the change, such as `new_purchase`. `unknown` when the order had no earlier status. |
| `data.changes.oldStatusName` | `string` | - | Name of the status before the change, as it was at the time. Left out when the order had no earlier status. |
| `data.changes.newStatus` | `string` | - | Category of the status after the change, such as `refunded`. |
| `data.changes.newStatusName` | `string` | - | Name of the status after the change, as it was at the time. |
| `data.changes.remark` | `string` | - | The note saved with the change. API changes sent without a `remark` show `Updated by API`; dashboard changes name the team member. |
| `data.changes.updatedAt` | `string` | - | When the change was made, ISO 8601 UTC. |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | `transactionId` is missing or isn't a string. Send it as a JSON string in a JSON body. |
| 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer <API_KEY>` with a current Community API key. |
| 403 | `API_KEY_PERMISSION_DENIED` | 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 data

| Status | Code | What to do |
| --- | --- | --- |
| 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 history 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 the order to its next status, or refund it.
- [Find other orders with List redemption orders by community](https://docs.returning.ai/api-reference/rewards-and-redemptions/list-redemption-orders-by-community.md): `POST /v1/redemption-transactions/by-community`.