> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/fuul-mcp-server/managing-referrals.md).

# Managing Referrals

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

{% hint style="warning" %}
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.
{% endhint %}

## 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...?"

{% hint style="info" %}
Returns the referrer's identifier, referral code, and rebate rate if any. Returns null referrer fields if the user has no referrer assigned.
{% endhint %}

***

## 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..."

{% hint style="info" %}
Assigns the referrer regardless of whether the user already has one. Does not affect referral code usage counters.
{% endhint %}

***

## 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..."

{% hint style="warning" %}
This only works if the user has **no existing referrer**. If they already have one, use `swap_user_referral_code` instead.
{% endhint %}

***

## 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"

{% hint style="warning" %}
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.
{% endhint %}

***

## 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"

{% hint style="info" %}
If the user was already removed, the tool returns `already_removed: true` instead of an error.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fuul.xyz/fuul-mcp-server/managing-referrals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.