Returning.AIDevelopers
v1

API reference / Rewards & Redemptions

.md

List redemption orders by community

List every redemption order in your community, newest first, one page at a time.

Last updated 26 Sep 2026API v1

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

When to use this

  • Sync new store orders into your fulfilment or back-office system.
  • Build a support queue of orders by status, such as everything still in New Purchase.
  • Find an order ID (ORD...) before you change its status or read its status 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.

Behaviour#

Orders come back newest first, by redemption time. The list has no filters: every order in your community is included, whatever its status, and any other body field is ignored. To track new orders, read from page 1 until you reach an order you already have. Orders redeemed while you page push older ones down, so the same order can appear on two pages; 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#

Both fields are optional. limit defaults to 10 and can be at most 100. A page past the last one returns an empty transactions list with the real total.

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-community \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "page": 1,
    "limit": 20
  }'

Response#

A 200 returns the page in data.transactions and the totals in data.pagination. Each order has two IDs. redemptionId is the order ID (ORD...) that every other redemption endpoint takes as transactionId. _id is an internal record ID; don't send it anywhere. Map statusID to your own status labels with List redemption statuses.

status#stringALWAYS
Result of the request.

Rulesuccess

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
Orders on this page, newest purchase first. Empty when there are none.

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.
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.
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.
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.
userData#object
The trader's account details.
email#string
The trader's email. null if the trader can't be matched.
userName#string
The trader's username. null if the trader can't be matched.
roles#string[]
Names of the trader's roles in your community.
pagination#objectALWAYS
Paging totals for the whole list.

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

total#integerALWAYS
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 there are no orders.

Eg1

code#stringALWAYS
Machine-readable result code.

RuleREDEMPTION_TRANSACTIONS_RETRIEVED

{
  "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",
        "userData": {
          "email": "trader@example.com",
          "userName": "sample_trader",
          "roles": ["@all"]
        }
      }
    ],
    "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
page or limit is not a whole number in range. detail names the field. Send page of 1 or more and limit from 1 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 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 order list 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 community endpoint",
  "detail": {
    "limit": "Number must be less than or equal to 100"
  }
}

Next step#

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