list_referral_rewards
List the referral ledger — the days or money each settled payment earned, whose it is and where it stands. Read-only, paginated.
Read the ledger behind the balances: one row per settled payment per side of a referral, to audit what an affiliate is owed, to see what a friend's welcome days did, or to reconcile a reversal. Both enum filters are typed before the service sees them.
Read-only. Rewards are written when a payment settles, made payable by the hold sweep, paid by a recorded payout and reversed by a refund; nothing here is written by hand.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same actions as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose referral ledger to list.
affiliate_idstringoptionalOptional affiliate UUID, to list one affiliate's rewards.
statusstringoptionalOptional filter: "pending", "approved", "paid", "applied" or "reversed".
beneficiarystringoptionalOptional filter: "referrer" or "friend".
limitintegeroptionalMaximum rewards to return per page (1..100).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "8e9f0a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "program_id": "6e2a7a4f-3b8c-4c21-9f6d-2a3b4c5d6e7f", "affiliate_id": "0b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b", "referral_id": "3c4d5e6f-7081-4a2b-9c3d-4e5f6a7b8c9d", "payment_id": "9f0a1b2c-3d4e-4f5a-9b0c-1d2e3f4a5b6c", "beneficiary": "referrer", "kind": "cash", "days": null, "amount": "12.0000", "currency_id": "f0e1d2c3-b4a5-4697-8877-665544332211", "currency": "USD", "status": "approved", "hold_until": "2026-10-23T14:20:01+00:00", "approved_at": "2026-10-23T15:00:00+00:00", "paid_at": null, "reversed_at": null, "applied_subscription_id": null, "reverses_reward_id": null, "payout_id": null, "created_at": "2026-10-09T14:20:01+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 1, "has_more": false }}A reward never changes after it is written
Each row is priced when the payment settled; editing the programme later
moves nothing here. A refund writes a reversal row of its own, with a
negative amount and reverses_reward_id naming the reward it cancels.
status is pending (inside the hold, or days waiting on the balance), approved (payable),
paid (recorded in a payout), applied (days banked on a membership) or reversed.
beneficiary is referrer or friend.
How it fails
VALIDATION_FAILEDstatus or beneficiary is not one of its cases.
RESOURCE_NOT_FOUNDunknown project_id, a project on another team, or one outside the token's
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-referral:view-any.
How is this guide?
Last updated on
list_referral_payouts
List the payouts recorded against a project's affiliates — how much, in which currency, and how many commissions each covered. Read-only, paginated.
list_referrals
List the friends affiliates brought in — how each arrived, whether they paid, and until when the affiliate earns on them. Read-only, paginated.