# ReferralCandy MCP

> ReferralCandy connects your AI agents directly to your affiliate and referral programs. It gives your agent full control over tracking advocates, registering purchases, managing campaigns, and analyzing performance metrics. Use it to automatically process pending rewards, list top referrers by period, or send direct campaign invites without logging into the platform.

## Overview
- **Category:** marketing-automation
- **Price:** Free
- **Tags:** referral-marketing, affiliates, loyalty, ecommerce

## Description

ReferralCandy gives your AI agent full control over managing your entire affiliate and referral program. You'll use this server to let your agent handle everything from tracking a new sign-up to processing payments, all without you having to log into the platform yourself.

**Analyzing Program Performance**

You can get a complete picture of how your referrals are doing across several tools. Your agent pulls overall performance statistics using `get_stats`. To see who's driving sales, it identifies and lists the **top-performing advocates** via `get_top_referrers`, or you can pull the full directory list of every advocate signed up with `list_referrers`. When you need deep data on a single user, your agent pulls all specific details about an individual referred customer using `get_referral` and fetches the profile information for a specific referring advocate through `get_referrer`.

To track sales activity, your agent reads every referral recorded in the program's history with `list_referrals`, or it filters results to focus on a narrow time window by calling `list_referrals_by_period`. For purchase data, you can list all purchases made by referred users—including order IDs and attribution details—using `list_purchases`. You'll also find that your agent checks the activity of your system connection using `check_referralcandy_status` to make sure everything's running smoothly.

**Managing Transactions and Rewards**

When a sale happens, you don't want to wait for manual processing. Your agent handles it instantly: calling `register_purchase` manually logs the purchase event. This action triggers the automatic calculation of rewards and queues up any necessary payouts for the advocate involved in that sale.

For payout management, your agent checks what needs paying out by running `list_pending_rewards`. You can also review your reward catalog and status list using `list_rewards` to ensure you're always set up with current incentives. If you need targeted marketing, your agent sends a new referral invitation directly to a specified user or group through `send_invite`, keeping your program active.

**Controlling Campaigns and System Data**

Your agent manages the underlying structure of your programs too. It provides full details for a specific referral marketing campaign using `get_campaign`, and it also fetches all existing campaigns when you call `list_campaigns`. If you need to know what invitations have been sent out, past or current, calling `list_invites` shows that history. To keep track of cash flow, your agent can list every reward type available in the system using `list_rewards`, and it also gives a full inventory of all rewards that are due but haven't cleared yet by listing pending payouts via `list_pending_rewards`. You don't need to log in; your AI client does the heavy lifting for you.

## Tools

### check_referralcandy_status
Verifies that the connection between your AI agent and ReferralCandy is active and working.

### get_campaign
Retrieves full details for a specific referral marketing campaign by its ID or name.

### get_referral
Pulls all specific data points about an individual referred user.

### get_referrer
Fetches the profile and details for a specific advocate or referring user.

### get_stats
Gathers overall, high-level performance statistics for your entire referral program.

### get_top_referrers
Identifies and lists the best advocates who have generated the most referrals or revenue recently.

### list_campaigns
Provides a full list of every campaign currently set up in your referral program.

### list_invites
Displays all past and current referral invitations that have been sent out by the system.

### list_pending_rewards
Checks for payouts or rewards that are due but have not yet been processed in the system.

### list_purchases
Lists all purchases made by referred users, including order IDs and attribution details.

### list_referrals_by_period
Filters and lists referrals, restricting results to a specific date range or period you specify.

### list_referrals
Generates a comprehensive list of every referral recorded in the program's history.

### list_referrers
Gets a complete directory list of all advocates who have ever signed up into the program.

### list_rewards
Displays a comprehensive catalog and status list of all reward types available in your system.

### register_purchase
Manually logs a purchase event, which triggers the automatic calculation and queuing of rewards for the advocate.

### send_invite
Sends a new referral invitation directly to a specified user or group within your program.

## Prompt Examples

**Prompt:** 
```
Can you find the top referrers in my ReferralCandy program for the last month?
```

**Response:** 
```
I've fetched your top advocates. The highest performer is 'Sarah Jenkins' with 42 successful referrals, generating $1,200 in revenue. Would you like me to send her a special campaign invite?
```

**Prompt:** 
```
Register a purchase of $150.00 for order #90210 by customer@example.com.
```

**Response:** 
```
Executing the purchase registration... The purchase for order #90210 has been successfully logged. ReferralCandy has attributed this to the advocate 'Michael T.' and a pending reward of $15 has been queued.
```

**Prompt:** 
```
List all pending referral rewards that need to be processed this week.
```

**Response:** 
```
Running the query... I found 8 pending rewards awaiting processing. Notable payouts include $50 for 'Alex' and $25 for 'Maria'. Would you like the full breakdown of these pending payouts?
```

## Capabilities

### Analyze Program Metrics
Retrieve overall program statistics and detailed lists of all referrals, advocates, and campaigns.

### Process Transactions
Register a purchase order directly to the system, automatically queuing rewards for advocates involved in the sale.

### Manage Payouts and Rewards
List all pending payouts and review current reward structures to ensure timely payments to advocates.

### Track Advocates
Identify the top-performing advocates, list all registered advocates, or retrieve a specific advocate's profile details.

### Control Campaigns and Invites
List active campaigns, view overall program stats, and send targeted referral invitations to users.

## Use Cases

### The End-of-Month Payout Audit
A marketing analyst needs to confirm all payouts for November. Instead of running five different reports, they ask their agent: 'List all pending rewards.' The agent runs `list_pending_rewards` and flags $50 in missing attribution. They then use `get_referral` on the involved user ID to find out why the referral wasn't fully tracked.

### Launching a Targeted Advocate Campaign
The e-commerce manager wants to boost sales from top users. They ask their agent: 'Who are my best advocates this quarter?' The agent runs `get_top_referrers`. Based on the list, the manager asks the agent to send a special incentive invite using `send_invite`.

### Manually Logging a Bulk Sale
A sales representative processes an offline corporate sale. Instead of waiting for web data sync, they tell their agent: 'Log $500 for order #XYZ.' The agent executes `register_purchase`, ensuring the reward is immediately queued and attributed to the correct advocate.

### Reviewing Historical Program Performance
The head of growth needs metrics for Q2. They ask their agent: 'Show me all referrals from April 1st to June 30th.' The agent uses `list_referrals_by_period`, providing a clean, filtered dataset without needing manual date range adjustments.

## Benefits

- **Automate Reward Processing:** Use `register_purchase` to log a sale. Your agent instantly queues the corresponding reward payout without you touching the UI. This moves transactions from manual data entry to conversational commands.
- **Deep Data Filtering:** Don't just look at totals. Tools like `list_referrals_by_period` let your agent filter referrals by exact dates, giving you precise metrics for quarterly reports that standard dashboards can't easily isolate.
- **Instant Advocate Intelligence:** Forget scrolling through hundreds of users. The `get_top_referrers` tool surfaces the highest-impact advocates immediately, allowing you to pivot directly into sending a retention bonus via `send_invite`.
- **Program Health Check:** Use `list_pending_rewards` and `list_rewards`. Your agent reviews what's owed versus what's configured, flagging payout discrepancies before they become cash flow issues.
- **Campaign Lifecycle Management:** Need to adjust outreach? The combination of `list_campaigns`, `get_campaign`, and `send_invite` means your agent can monitor, modify, and execute campaign rollouts—all in one chat session.

## How It Works

The bottom line is that your AI client uses the API keys to execute complex marketing and reporting actions against your active ReferralCandy account.

1. Subscribe to the ReferralCandy server and paste your API keys (you find these in your developer settings).
2. Your AI agent uses a tool like `check_referralcandy_status` to verify connectivity and confirm credentials.
3. The agent then executes multi-step commands, such as listing referrals by period (`list_referrals_by_period`) followed by registering purchases (`register_purchase`).

## Frequently Asked Questions

**How do I find out which advocates are doing well with get_top_referrers?**
The `get_top_referrers` tool lists your highest-performing advocates. It ranks them based on key metrics, letting you know exactly who to contact for a bonus or recognition.

**Can I list referrals from only last month using list_referrals_by_period?**
Yes. `list_referrals_by_period` lets you filter the entire referral history by a specific start and end date, making it perfect for monthly reporting.

**How do I make sure rewards are paid out correctly? list_pending_rewards helps?**
The `list_pending_rewards` tool shows exactly what payouts are ready to go. This lets you confirm the system is keeping up with sales and that no payments are stuck.

**What if I need to manually log a purchase? Should I use register_purchase?**
Yes, `register_purchase` is the tool for it. It ensures that even if the purchase wasn't made through the standard checkout flow, the corresponding reward payout gets queued.

**Before I run any queries, how can I use check_referralcandy_status to confirm my API keys work?**
Running `check_referralcandy_status` confirms your connection and credentials immediately. It returns a simple success code if the server recognizes your keys and has live access. If you get an error, it usually means the key is expired or wasn't correctly entered in Vinkius.

**If I run list_purchases for thousands of records, will I get all of them? Does it handle pagination?**
The system handles large data sets by checking for paginated results. If the initial call doesn't return everything you expect, your AI client should automatically request the next page using the provided cursor or offset token to gather the complete list.

**What happens if I use get_referral with a referral ID that doesn't exist?**
The tool returns a specific 'Not Found' error code and an explanatory message. This tells your agent immediately that the provided ID is invalid, preventing it from running unnecessary follow-up logic.

**I need to send out many invites quickly; are there any limits when I use send_invite?**
Yes, API rate limits apply. If you try sending a massive batch of invitations in rapid succession, the system will return a 429 'Too Many Requests' error. You’ll need to implement a short delay or queue the requests.

**Can my AI automatically register a new purchase to trigger a referral reward?**
Yes! Use the `register_purchase` tool providing the buyer's email, order amount, and order ID. Your agent will send this data to ReferralCandy, triggering the referral attribution and payout flow instantly.

**How do I easily find out who my best performing advocates are?**
Simply ask the agent to run the `get_top_referrers` action. It will compile your highest-performing ambassadors ranked by total successful referrals and the total revenue they generated for your store.

**Can I check if a specific customer has any pending referral rewards?**
Absolutely. By using the `list_pending_rewards` tool and filtering by the customer's email, your agent can instantly fetch their reward status and payout timeline without you needing to open the dashboard.