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).
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
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.
