sales-skills/sales-referral-factory

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.