sales-referral-factory

name	sales-referral-factory
description	Referral Factory (referral-factory.com) platform help — no-code referral program builder for SaaS, ecommerce, and service businesses: 100+ branded campaign templates, referral links + codes, reward issuing (cash, gift cards, Stripe credits/coupons, commissions, custom), fraud detection, and white-label. REST API (api.referral-factory.com/api/v2, Bearer token, POST /users with referrer attribution, PUT /users/qualification, /rewards endpoints), outbound + inbound webhooks (no documented HMAC), and native HubSpot/Salesforce/Stripe/Zapier/Make/n8n syncs. Use when adding referrers via the API and attributing the referrer, qualifying referred users to trigger rewards, reacting to webhooks, issuing or canceling due rewards, deciding referral vs affiliate, or choosing the Basic/Pro/Enterprise plan. Do NOT use for referral/audience-growth strategy across tools (use /sales-audience-growth), affiliate program design (use /sales-affiliate-program), or email deliverability (use /sales-deliverability).
argument-hint	[describe what you need help with in Referral Factory]
license	MIT
version	1.0.0
tags	["sales","audience-growth","referral","platform"]

Referral Factory 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) Add referrers / referred users via the API (and attribute the referrer)
   • B) Qualify a referred user to make a reward become due, then issue/cancel rewards
   • C) Send users out (outbound webhook) or qualify them in (inbound webhook)
   • D) Pick + set up a campaign type — single/double-sided, invite-only, refer-to-win
   • E) Connect Referral Factory to a CRM/ESP/Stripe (native, Zapier, Make, n8n)
   • F) Decide referral vs affiliate, or measure whether referrals are incremental
   • G) Fix a problem — referrals not attributing, custom-domain fees, payout methods, plan limits

2. API or no-code? A code integration → REST API (Authorization: Bearer) + webhooks. No endpoint to host → native connectors or Zapier/Make/n8n.

Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.

Step 2 — Route or answer directly

If the question is about...	Route to...
Referral / audience-growth strategy across tools (which tool, viral mechanics, incrementality)	/sales-audience-growth {question}
Designing a commission-based affiliate program across tools	/sales-affiliate-program {question}
Email deliverability of referral/notification emails	/sales-deliverability {question}
Connecting Referral Factory to a CRM/ESP/Stripe generically (iPaaS)	/sales-integration {question}

When routing, give the exact command, e.g. "This is a strategy question — run: /sales-audience-growth measure whether my referral program is incremental vs organic word-of-mouth".

Step 3 — Referral Factory platform reference

Read references/platform-guide.md for the full reference — the campaign-type + module map (what's API vs widget vs UI-only), the user-based pricing model and plan-gated features, the user/campaign/reward data model with JSON shapes, and quick-start recipes (create + attribute a referrer; qualify to trigger a reward; issue a due reward).

Read references/referral-factory-api-reference.md for the integration surface — base https://api.referral-factory.com/api/v2, Bearer auth (one token per account), POST /users with the referrer field, PUT /users/qualification, the /rewards/{due,issue,cancel,dashboard,issued} endpoints, cursor pagination (per_page ≤250, links.next), the 600-calls/min limit, and the outbound/inbound webhooks (no documented HMAC).

Answer using only the relevant section. Don't dump the full reference.

Step 4 — Actionable guidance

Focus on the user's specific situation:

• Attribute the referrer on create. POST /users makes a Person Referring by default; pass referrer: {field: "code"|"id"|"email", value: ...} to make it a Person Invited credited to that referrer. Omit it and the referral isn't attributed — the #1 integration bug.
• Qualifying is what triggers rewards. A referral only becomes a qualified referral (and a reward becomes due) when you call PUT /users/qualification (by id, code, or email+campaign_id) or send the inbound qualify webhook. Adding the user is not enough.
• Rewards are a two-step flow. Qualification makes a reward due; you then POST /rewards/issue/{id} to actually issue it (or /rewards/cancel/{id}). List what's owed via GET /rewards/due/{metric}.
• Use webhooks, not polling. Outbound fires on new user and on qualified referral — pipe those to your CRM/ESP. There's no documented HMAC, so treat the endpoint as a secret URL, dedupe, and re-verify via GET /users/{identifier} before paying out.
• Mind the plan gates. API/webhooks are on every plan, but white-label, custom domain, and SSO need Pro; custom HTML and on-prem need Enterprise. Pricing scales by users (Basic ~$200 / Pro ~$400 / Enterprise ~$1,000).
• Payout reality. Rewards go out as PayPal cash, gift cards (200+ countries), Stripe credits/coupons, commissions, or custom — no direct bank transfer; pick a reward type your audience can actually redeem.

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.

Gotchas

Best-effort from research (2026-06) — pricing/features verified against the marketing site + reviews; confirm specifics in-account.

1. Referrals don't attribute without referrer. A bare POST /users is a standalone Person Referring; you must pass the referrer object (or route signups through the referral link) to credit the referrer.
2. Adding ≠ qualifying. Rewards only become due after PUT /users/qualification (or the inbound qualify webhook). Forgetting this is why "my referrals never trigger rewards."
3. No documented webhook HMAC. Don't trust an unsigned webhook blindly — secret URL, re-verify via the API, and make handlers idempotent (a new-user and a later qualified event can both arrive for the same person).
4. One API token per account. Generating a new token deactivates the old one — rotating a key breaks every existing integration using the previous token.
5. Custom domain & white-label cost more. Removing branding/using your own domain requires Pro; reviewers specifically flag custom-domain fees. Budget the plan, not just the base price.
6. No direct bank payouts. Rewards are PayPal/gift card/Stripe/commission/custom — some users want bank transfer and it isn't offered. Set reward expectations accordingly.
7. Unique-link skepticism. Some referred people sign up off-link (organic WOM) and it's hard to tell program-driven from organic — measure incrementality, don't assume every signup is the program's. Route the strategy question to /sales-audience-growth.
8. Referral ≠ affiliate. Referral Factory runs customer referrals (rewards/discounts); for a commission-based affiliate/partner program with a partner portal, compare dedicated tools via /sales-affiliate-program.
9. api. host vs help-doc example. The OpenAPI base is api.referral-factory.com/api/v2; one help article shows referral-factory.com/api/v2. Use the api. host and verify in-account.

Related skills

• /sales-audience-growth — Referral / audience-growth strategy across tools (Referral Factory is one of the referral platforms covered) — viral mechanics, tool selection, incrementality
• /sales-affiliate-program — Designing a commission-based affiliate (partner) program across tools — the affiliate counterpart to Referral Factory's customer referrals
• /sales-email-marketing — Email sequences for the referral list you sync out of Referral Factory
• /sales-integration — Connecting Referral Factory to a CRM/ESP/Stripe via webhooks/Zapier/Make/n8n
• /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: Add a referred user and attribute the referrer via the API (developer/automation)

User says: "When someone signs up through a friend's link in my app, how do I add them to my Referral Factory campaign and credit the friend?" Skill does: Walks Recipe 1 — POST /api/v2/users with campaign_id, first_name, email, and the referrer object ({field: "code", value: "<friend's code>"}), authenticated by Authorization: Bearer <token>. Stresses that omitting referrer makes a standalone Person Referring (no attribution), and that you must later PUT /users/qualification to turn it into a qualified referral that makes a reward due. Notes the no-code native/Zapier path as an alternative. Result: The friend is correctly credited and the referral is ready to qualify.

Example 2: Qualify a referral and issue the reward

User says: "A referred trial converted to paid — how do I mark it qualified and pay the reward?" Skill does: PUT /api/v2/users/qualification with {email, campaign_id, qualified: true} (or by id/code). Explains qualification makes the reward due; then GET /rewards/due/{metric} to find it and POST /rewards/issue/{id} to issue (or /rewards/cancel/{id}). Flags idempotency (re-verify before issuing) and that payout is PayPal/gift card/Stripe, not bank transfer. Result: The converted referral is qualified and its reward issued through the API.

Example 3: Referral or affiliate — which do I need?

User says: "Should I use Referral Factory or set up an affiliate program?" Skill does: Distinguishes the models — Referral Factory runs customer referrals (existing customers refer friends for rewards/discounts), whereas an affiliate/partner program pays commissions to recruited promoters with a partner portal and tracking links. Recommends Referral Factory for customer word-of-mouth and routes the affiliate decision: "run: /sales-affiliate-program design a commission-based affiliate program." Notes Referral Factory can pay commissions but isn't a full affiliate-partner platform. Result: User picks the right model and is handed to the right skill.

Troubleshooting

My referrals are added but never trigger a reward

Symptom: Users appear in the campaign but no reward ever becomes due. Cause: The referred user was created but never qualified — adding a user does not qualify it, and rewards only become due on qualification. Solution: Call PUT /api/v2/users/qualification with the user's id/code (or email + campaign_id) and qualified: true, or send the inbound qualify webhook with their code/coupon. Then GET /rewards/due/{metric} and POST /rewards/issue/{id}. Also confirm the original POST /users included the referrer so the referral is attributed in the first place.

My reward webhook fired twice / paid out twice

Symptom: A referrer's reward was issued more than once. Cause: A new-user event and a later qualified event (and retries) can arrive for the same person, and there's no HMAC to dedupe on a signature. Solution: Make the handler idempotent — key on the user id/code (or the due-reward id), persist what you've already issued, and re-verify the user via GET /users/{identifier} before calling POST /rewards/issue. Restrict the webhook endpoint to a secret URL.

I can't use my own domain / branding looks like Referral Factory

Symptom: Referral pages show Referral Factory branding or won't run on your domain. Cause: White-label (remove branding) and custom domain are plan-gated to Pro+; custom HTML upload is Enterprise-only. Solution: Upgrade to Pro for white-label + custom domain (or Enterprise for custom HTML). If you only need API/webhooks and reward logic, Basic already includes those — weigh the branding gates against cost (reviewers flag custom-domain fees), or compare alternatives via /sales-audience-growth.