🤝Managing Referrals

The Fuul MCP lets you read and manage referral attributions directly from your AI assistant — without going through the dashboard.

All referral management tools require a project API key, not the dashboard login. Pass it via project_api_key on each call, or set the FUUL_MCP_PROJECT_API_KEY environment variable.

Use cases

Master affiliate structures

Some programs have affiliate leaders who onboard other affiliates through direct deals — not through referral codes. For example, a regional leader might bring ten affiliates to your program verbally or via an offline agreement. In these cases, you need to manually assign those affiliates under the correct referrer to reflect the structure you negotiated with them.

The MCP handles all of this: checking current attributions, assigning a referrer directly, moving users between codes, and removing attributions entirely.

---

1. Check who referred a user

Before making changes, look up the current referral attribution for any user:

"Who referred user 0xABC...?"

Returns the referrer's identifier, referral code, and rebate rate if any. Returns null referrer fields if the user has no referrer assigned.

---

2. Assign a referrer directly (admin override)

Use this when a referral relationship was agreed upon outside the platform — no referral code was used, but you need to reflect the attribution in Fuul.

"Set the referrer of user 0xABC... to 0xXYZ..."

Assigns the referrer regardless of whether the user already has one. Does not affect referral code usage counters.

---

3. Redeem a referral code for a user

Use this to redeem a referral code on behalf of a user. The referrer is the code owner — no need to pass a referrer identifier:

"Assign referral code PROMO2024 to user 0xABC..."

This only works if the user has no existing referrer. If they already have one, use swap_user_referral_code instead.

---

4. Move a user between referral codes

Use this to reassign a user from one referral code to another — for example, when a user entered through the wrong code and needs to be moved to the correct one:

"Move user 0xABC... from referral code OLD to referral code NEW"

This runs as two separate steps. If the second step fails after the first one completes, the user will be left without a referrer. The MCP will flag this in the response — if that happens, complete the assignment using the direct assign or redeem code tools.

---

5. Remove a user from a referral code

Use this to fully unlink a user from a referral code — deletes the attribution and decrements the code's usage count:

"Remove user 0xABC... from referral code PROMO2024"

If the user was already removed, the tool returns already_removed: true instead of an error.