ReferralHero platform help — full-stack referral, affiliate, waitlist, contest, and NPS platform with REST API, webhooks, Zapier, native ESP connectors, multi-level referral tracking (Level 1/2/3), coupon groups, anti-fraud, and a 5,000 calls/hour limit. Use when referrals aren't tracking, deciding between Free (no API) vs PRO (API + webhooks) vs PREMIUM (ReCaptcha + SMS Verification), auth failing with `no_token` or `Bearer` vs `X-API-Key`, Level 2/3 counts off from calling `level_2_all_referrals` not `level_2_referrals`, bulk 429s from not chunking the 500-transaction `add_bulk_transactions` limit, coupon endpoints 404 without a coupon group, reward fulfillment (`promote` then `unlock_promoted_reward`) failing, or comparing to SparkLoop/ReferralKit/GrowSurf. Do NOT use for newsletter audience growth (use /sales-audience-growth), merge-tag referrals (use /sales-referralkit), SparkLoop recommendations (use /sales-sparkloop), or affiliate strategy across tools (use /sales-affiliate-program).
ReferralHero platform help — full-stack referral, affiliate, waitlist, contest, and NPS platform with REST API, webhooks, Zapier, native ESP connectors, multi-level referral tracking (Level 1/2/3), coupon groups, anti-fraud, and a 5,000 calls/hour limit. Use when referrals aren't tracking, deciding between Free (no API) vs PRO (API + webhooks) vs PREMIUM (ReCaptcha + SMS Verification), auth failing with `no_token` or `Bearer` vs `X-API-Key`, Level 2/3 counts off from calling `level_2_all_referrals` not `level_2_referrals`, bulk 429s from not chunking the 500-transaction `add_bulk_transactions` limit, coupon endpoints 404 without a coupon group, reward fulfillment (`promote` then `unlock_promoted_reward`) failing, or comparing to SparkLoop/ReferralKit/GrowSurf. Do NOT use for newsletter audience growth (use /sales-audience-growth), merge-tag referrals (use /sales-referralkit), SparkLoop recommendations (use /sales-sparkloop), or affiliate strategy across tools (use /sales-affiliate-program).
argument-hint
[describe what you need help with in ReferralHero]
What's your campaign type? Referral / Affiliate / Waitlist / Contest / NPS — the data model and which endpoints matter differ.
What's your ESP? Drives whether the native integration applies (Mailchimp, Kit, AWeber, Klaviyo, ActiveCampaign, SendLane) or you need Zapier/webhook/API patterns.
Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.
Step 2 — Route or answer directly
If the question is about...
Route to...
General newsletter audience growth strategy across all platforms
/sales-audience-growth [question]
General newsletter monetization
/sales-newsletter [question]
No-code newsletter-only referrals with merge-tag insertion (Copyhackers)
If the question is ReferralHero-specific, continue to Step 3.
Step 3 — ReferralHero platform reference
Read references/platform-guide.md for the full reference — feature gating, tier comparison, ESP integration flow, multi-level referral mechanics, anti-fraud controls, and comparisons with SparkLoop / ReferralKit / Viral Loops / GrowSurf / KickoffLabs.
Read references/referralhero-api-reference.md for the verbatim REST API documentation — authentication (Bearer token / X-API-Key), base URL (https://app.referralhero.com/api/v2), full endpoint reference (Lists, Subscribers, Coupons, Rewards, Levels 1/2/3 referrals, transactions, bulk transactions, qualify/unqualify, promote/unlock_promoted_reward), rate limits (5,000 req/hr soft), and error codes.
Answer the user's question using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
Focus on the user's specific situation:
Free tier (25 subscribers max) — useful only for proof of concept. Real campaigns need PRO ($199/mo, 10K members) or PREMIUM ($399/mo, 50K members). The Waitlist/Contest variant of PREMIUM is also $199/mo for 50K subscribers and adds broadcasts.
API available from PRO upward — the Free tier excludes API access, so don't promise programmatic workflows on the Free tier. Confirm the user's plan before recommending API-driven recipes.
Auth: Authorization: Bearer YOUR_API_TOKEN is the canonical form. X-API-Key: YOUR_API_TOKEN is the documented fallback when the client can't send Authorization. Don't mix headers.
Rate limit is per-token, 5,000/hr soft — contact ReferralHero support to raise it. Returns HTTP 429 with too_many_calls error code on overage.
Bulk transactions are capped at 500 per request (POST .../subscribers/add_bulk_transactions) — chunk larger imports.
Multi-level referral mechanics: separate endpoints for Level 1 / 2 / 3 referrals and Level 2 / 3 "all referrals" (qualified + unqualified). Use the right endpoint or the count will look wrong.
Promote → unlock_promoted_reward is a two-step manual reward fulfillment flow — for milestone-based rewards, configure them on the campaign and call promote after the subscriber crosses the threshold, then unlock_promoted_reward with the reward_id.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research — review these, especially items about plan-gated features that may shift.
API access starts at PRO ($199/mo). Free tier (25 subs) has NO API access — don't quote programmatic workflows to anyone still on Free. Webhooks also start at PRO.
Rate limit is 5,000 calls/hour (soft) per token. Exceeding returns HTTP 429 with too_many_calls error code. For high-volume imports, use add_bulk_transactions (500/request) instead of per-subscriber calls and request a limit increase via support.
ReCaptcha and SMS Verification are PREMIUM-only ($399/mo). PRO has anti-fraud, coupon codes, custom sender domain, and automation emails — but not the strongest abuse controls. If your program is a target for fraud, budget PREMIUM from day one.
Bulk transactions max 500 per request. Larger imports must be chunked. The endpoint expects a JSON transactions array, not multipart.
Multi-level endpoints have separate "all" vs "confirmed" variants.level_2_all_referrals includes unqualified referrals; level_2_referrals shows only confirmed. Calling the wrong one explains "the count is off" complaints. Same pattern at Level 3.
Promote + unlock_promoted_reward is a two-step flow. First POST .../subscribers/:id/promote, then POST .../subscribers/:id/unlock_promoted_reward with the reward_id. Skipping promote causes unlock_promoted_reward to silently fail.
Coupons live under coupon groups, not standalone.POST .../coupon_groups first, then POST .../coupons with the coupon_group_id. Importing flat lists without a group fails.
Lifetime-deal customers got migrated to monthly subs. Capterra reviews show frustration with the pricing transition — if the user mentions a "lifetime" plan they bought years ago, that's the context; current plans are subscription-only.
Authentication header is single-header, not both. Send EITHER Authorization: Bearer ... OR X-API-Key: ... — sending both has undocumented behavior. Prefer Authorization unless your client strips it.
Native ESP integrations may double-add subscribers. If you connect Mailchimp (or Kit/AWeber/etc.) AND also POST to /subscribers via API, you'll get duplicate adds. Pick one mechanism per campaign.
No MCP server. AdButler and some newsletter tools ship MCP — ReferralHero does not, as of research date 2026-06-01. Confirm before claiming MCP support.
Related skills
/sales-audience-growth — Newsletter audience growth strategy (referrals + cross-promotion + lead magnets across all platforms)
/sales-newsletter — Newsletter monetization (paid subs, sponsorships, ad networks)
/sales-referralkit — ReferralKit (no-code Morning Brew-style merge-tag-driven referrals, free up to 10K leads, no API)
/sales-affiliate-program — General affiliate program strategy and platform selection
/sales-mailchimp — Mailchimp platform help (one of ReferralHero's native ESP integrations)
/sales-kit — Kit / ConvertKit platform help (native ESP integration)
/sales-mailerlite — MailerLite platform help (Zapier-based integration)
/sales-klaviyo — Klaviyo platform help (native ESP integration)
/sales-activecampaign — ActiveCampaign platform help (native ESP integration)
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: PRO vs PREMIUM decision for a fraud-prone giveaway campaign
User says: "I'm running a viral giveaway expecting 20K signups and worried about fake referrals. PRO or PREMIUM?"
Skill does: Recommends PREMIUM ($399/mo) because it adds ReCaptcha and SMS Verification — both essential for fraud-prone viral campaigns. Notes PRO ($199/mo, 10K members) wouldn't cover 20K anyway. Mentions PREMIUM Waitlist/Contest variant at $199/mo for 50K subscribers if the contest is the entire campaign and the standard referral feature mix isn't needed. Suggests turning on anti-fraud + coupon validation + reward review workflow regardless of tier.
Result: User picks PREMIUM with ReCaptcha + SMS Verification on, sets up reward review for top referrers.
Example 2: Setting up API + first subscriber add
User says: "I'm on the PRO plan. How do I add a subscriber via the API and assign them a referrer?"
Skill does: Provides authentication header (Authorization: Bearer YOUR_API_TOKEN), base URL (https://app.referralhero.com/api/v2), and a cURL example: POST /lists/:uuid/subscribers with email, name, and referrer (the referrer's referral code or unique identifier). Notes that double_optin=true matches the campaign's setting if confirmation is required. Points to references/referralhero-api-reference.md for the full parameter list, and warns about double-adds if Mailchimp/Kit native integration is also connected.
Result: User makes a successful first API call, sees the new subscriber with attribution to the referrer, and knows to disable one of the dual subscription paths.
Example 3: Multi-level referral counts look wrong
User says: "I have multi-level referrals enabled. My Level 2 count seems off — way higher than what I see in the dashboard."
Skill does: Asks which endpoint they're hitting. If they're calling GET /lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals that includes UNqualified referrals — dashboard typically shows only qualified. Recommends level_2_referrals (confirmed only) for parity with the dashboard view. Notes the same pattern at Level 3. Suggests qualify / unqualify endpoints to manually re-classify suspicious referrals.
Result: User switches endpoint, counts match the dashboard, and adds qualify/unqualify into their fraud-review workflow.
Troubleshooting
Authentication failing with no_token error
Symptom: API requests return no_token despite sending the header
Cause: Header capitalization, missing Bearer prefix, or sending both Authorization and X-API-KeySolution: Use exactly Authorization: Bearer YOUR_API_TOKEN (capital A, lowercase bearer per HTTP spec is also accepted, but Bearer with capital B is documented). If your HTTP client strips Authorization headers, fall back to X-API-Key: YOUR_API_TOKEN — but never send both. Verify the token from ReferralHero dashboard > Account > API; tokens are per-account, not per-list.
too_many_calls (HTTP 429) on bulk import
Symptom: Bulk subscriber import errors out partway with HTTP 429 too_many_callsCause: Hit the 5,000 calls/hour soft rate limit by POSTing per-subscriber instead of using bulk endpoints
Solution: Switch single-subscriber loops to POST /lists/:uuid/subscribers/add_bulk_transactions (500 transactions per request). Add exponential backoff with Retry-After respect. For sustained high volumes, contact ReferralHero support to raise the rate limit.
Webhook not firing on referral confirmation
Symptom: Configured a webhook for confirmation events but it never fires
Cause: Webhooks are PRO+ (not Free), the campaign's double_optin setting interacts with confirmation timing, or the subscriber was added without a referrer value
Solution: Confirm plan tier includes webhooks (PRO and PREMIUM do). Check that the campaign has double_optin configured correctly — if on, confirmation requires the referee to click the confirmation email. For API-added subscribers, ensure referrer is set to the referrer's referral code or unique identifier, otherwise no attribution event fires.
Reward not unlocking after milestone
Symptom: Subscriber hit the milestone threshold but the reward email never sent
Cause: Reward fulfillment is a two-step manual flow on the API path — promote then unlock_promoted_rewardSolution: First call POST /lists/:uuid/subscribers/:subscriber_id/promote to mark the subscriber as eligible for the next reward, then POST /lists/:uuid/subscribers/:subscriber_id/unlock_promoted_reward with the reward_id. If you're using the UI-side automatic milestone rewards, check that the milestone threshold is set on the campaign and the subscriber's qualified-referral count actually exceeds it (NOT all-referrals count).
Coupon import returns 404
Symptom: POST /lists/:uuid/coupons with an array of codes returns 404
Cause: Coupons must belong to a coupon group; the group ID is required in the request
Solution: First create a coupon group: POST /lists/:uuid/coupon_groups with name, coupons (initial array), and active: true. Capture the returned id. Then add more coupons via POST /lists/:uuid/coupons with coupon_group_id set to that ID.
