trackRedemptionBatchStatus(claim_id)
Purpose
Allows users to check the real-time status of their redemption for under-threshold prizes.
This endpoint surfaces where their claim is in the payout or batching lifecycle.
Endpoint
GET /api/track-redemption-status/{claim_id}
Authorization
- Required Scope:
user.read
- Token: Bearer Token from authenticated user session
Parameters
| Name |
Type |
Required |
Description |
| claim_id |
string |
✅ |
Unique ID assigned to user's redemption claim |
Response: Success (200 OK)
{
"claim_id": "claim_002",
"batch_id": "batch-045",
"batch_status": "processing",
"estimated_payout_date": "2025-06-30T00:00:00Z"
}
Status Values
| Value |
Meaning |
| queued |
Claim added but not yet assigned to a batch |
| processing |
Assigned and undergoing payout checks |
| redeemed |
Payout completed; funds in queue or sent |
Error States
| HTTP Code |
Error Key |
Description |
| 404 |
claim_not_found |
The claim ID does not exist |
| 403 |
unauthorized |
User not permitted to access this claim |
Integration Notes
- Used by frontends (e.g., mobile apps, partner dashboards) to show real-time status.
- Consider caching frequent queries at the batch level to reduce DB strain.
- Claims that escalate to KYC will exit this flow and trigger
submitKYC() instead.