sales-referralhero

What this skill does

# ReferralHero Platform Help

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

1. **What are you trying to do?**
   - A) Pick a tier — Free (25 subs) vs PRO $199/mo (10K) vs PREMIUM $399/mo (50K)
   - B) Set up the REST API — authentication, base URL, first request
   - C) Add or track subscribers via API (single, bulk, with transaction data)
   - D) Configure webhooks for referral confirmation events
   - E) Integrate a native ESP connector (Mailchimp, Kit, AWeber, Klaviyo, ActiveCampaign, SendLane)
   - F) Multi-level referral tracking (Level 1/2/3) — counts not appearing or downline math is off
   - G) Coupon codes — create coupon groups and bulk-import codes
   - H) Compare ReferralHero against SparkLoop / ReferralKit / Viral Loops / GrowSurf / KickoffLabs
   - I) Hit the 5,000 calls/hour rate limit — getting 429 too_many_calls
   - J) Reward fulfillment workflow — promote subscriber + unlock_promoted_reward

2. **What's your campaign type?** Referral / Affiliate / Waitlist / Contest / NPS — the data model and which endpoints matter differ.

3. **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) | `/sales-referralkit [question]` |
| SparkLoop paid recommendations + partner network | `/sales-sparkloop [question]` |
| Affiliate program strategy across many tools | `/sales-affiliate-program [question]` |
| ESP setup (Mailchimp, Kit, MailerLite, AWeber, Klaviyo, ActiveCampaign) | `/sales-mailchimp`, `/sales-kit`, `/sales-mailerlite`, `/sales-klaviyo`, `/sales-activecampaign` |

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.*

1. **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.
2. **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.
3. **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.
4. **Bulk transactions max 500 per request.** Larger imports must be chunked. The endpoint expects a JSON `transactions` array, not multipart.
5. **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.
6. **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.
7. **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.
8. **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.
9. **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.
10. **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.
11. **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-sparkloop` — SparkLoop (referrals + paid recommendations + partner network across 25+ ESPs)
- `/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 ro