get_referral_affiliate
Fetch one affiliate with their code, status, days balance and what they are owed per currency. Read-only; never their payout details.
Read one affiliate in full. The row is the one
list_referral_affiliates emits plus balances,
the figures a payout is recorded against: pending (inside the hold), earned, payable (what
record_referral_payout may record) and
paid_out, per currency, each a decimal string.
Call it before recording a payout, to read the payable balance rather than assuming it.
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 the affiliate belongs to.
affiliate_id*stringUUID of the affiliate to fetch.
What it returns
{ "data": { "id": "0b1c2d3e-4f50-4617-8a9b-0c1d2e3f4a5b", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "program_id": "6e2a7a4f-3b8c-4c21-9f6d-2a3b4c5d6e7f", "member_id": "a1b2c3d4-e5f6-4718-8a9b-0c1d2e3f4a5b", "code": "ADA2026", "status": "approved", "days_balance": 0, "balances": [ { "currency_id": "f0e1d2c3-b4a5-4697-8877-665544332211", "pending": "12.0000", "earned": "52.0000", "payable": "30.0000", "paid_out": "10.0000" } ], "joined_at": "2026-10-08T09:05:00+00:00", "approved_at": "2026-10-08T10:00:00+00:00", "created_at": "2026-10-08T09:05:00+00:00", "updated_at": "2026-10-08T10:00:00+00:00" }}Payout details never travel
The wallet address or PayPal email an affiliate typed when the creator asked is their money, shown only on the dashboard when the creator pays. No tool, endpoint or webhook carries it.
days_balance is membership days earned while the affiliate held no live membership, banked
onto their next purchase; on a free-days programme the days a live member earned are already on
their membership and not here.
How it fails
RESOURCE_NOT_FOUNDunknown project_id or affiliate_id, an affiliate of another project, or a
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-referral:view.
How is this guide?
Last updated on
get_referral
Fetch one referral — the affiliate, the friend's member id, how they arrived, whether they paid and until when the affiliate earns on them. Read-only.
get_referral_program
Fetch a project's Referral Program — what referrers earn, what friends receive, who may join, the hold, the creator's terms and the plans that count. Read-only.