skills/marketing-growth/referral-viral-loops/SKILL.md
Build referral mechanics with dual-sided rewards, unique tracking links, viral coefficient optimization, and anti-fraud controls for referral abuse
npx skillsauth add finsilabs/awesome-ecommerce-skills referral-viral-loopsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Word-of-mouth referral programs are one of the lowest-cost customer acquisition channels — referred customers have 37% higher retention rates and 25% higher LTV than non-referred customers. A dual-sided referral (reward both the referrer and the new customer) typically outperforms one-sided rewards by 2–3×. Dedicated referral apps (ReferralCandy, Friendbuy, Yotpo Loyalty) handle link generation, reward fulfillment, and fraud controls without custom code.
| Platform | Best For | Shopify | WooCommerce | BigCommerce | Price | |----------|---------|---------|-------------|-------------|-------| | ReferralCandy | Simple setup, all major platforms | App Store | Plugin | App Marketplace | $59+/mo | | Friendbuy | Mid-market DTC, A/B testing rewards | App Store | Via JS | Via JS | $249+/mo | | Yotpo Loyalty | Brands already using Yotpo | App Store | Limited | App Marketplace | $199+/mo | | Smile.io Referrals | Already using Smile.io for loyalty | App Store | Plugin | App Marketplace | Included in $49/mo plan | | Rewardful | SaaS + ecommerce via Stripe | Via Stripe | Via Stripe | Via Stripe | $49+/mo | | AffiliateWP | WooCommerce-native | — | Plugin | — | $149/yr |
Recommendation: Use ReferralCandy for most stores — quick setup, dual-sided rewards built in, fraud detection included, and competitive pricing. If you are already using Smile.io for loyalty, add their referral module instead of a separate app.
Before installing anything, define the reward structure:
Dual-sided reward (recommended):
Single-sided reward (simpler but lower share rate):
Minimum order for referral to qualify: $30 (prevents micro-order gaming)
Refund window: Wait 7–14 days after the referee's order before granting the referrer reward — this prevents rewards on returned orders.
yourstore.com/?via=sarah123)yourstore.com/?ref=AFFILIATE_IDAlternative: Install ReferralCandy for WooCommerce (plugin) for a simpler dual-sided setup.
Use a dedicated referral API platform like Friendbuy or Rewardful rather than building from scratch. These provide:
If you must build custom, the core components are:
// Generate a unique referral code per customer
async function generateReferralCode(customerId: string): Promise<string> {
const existing = await db.referralLinks.findOne({ where: { customerId } });
if (existing) return existing.code;
const customer = await db.customers.findById(customerId);
const baseCode = customer.firstName.replace(/[^a-zA-Z]/g, '').toUpperCase().slice(0, 6);
let code = `${baseCode}${Math.floor(100 + Math.random() * 900)}`;
while (await db.referralLinks.findOne({ where: { code } })) {
code = `${baseCode}${Math.floor(100 + Math.random() * 900)}`;
}
await db.referralLinks.create({ customerId, code, clicks: 0, conversions: 0 });
return code;
}
// Attribute referral on order completion — check cookie for referral code
async function attributeReferral(order: Order, referralCode: string | null) {
if (!referralCode) return;
const referralLink = await db.referralLinks.findByCode(referralCode);
if (!referralLink) return;
if (referralLink.customerId === order.customerId) return; // no self-referral
// Check if this email has already been referred (one referral per email per program)
const existing = await db.referralConversions.findOne({ where: { refereeEmail: order.customerEmail } });
if (existing) return;
await db.referralConversions.create({
referralLinkId: referralLink.id,
referrerId: referralLink.customerId,
refereeEmail: order.customerEmail,
orderId: order.id,
orderValue: order.subtotal,
status: 'pending', // set to 'approved' after 7-day refund window
});
// Grant referee discount immediately (e.g., store credit or discount code)
// Schedule referrer reward 7 days after order — after refund window
}
Highest-traffic placements:
In ReferralCandy: go to Promote → Post-Purchase Popup to enable the automatic widget and Promote → Emails to configure referral invitation emails.
| Metric | Target | Where to Find | |--------|--------|---------------| | Share rate (% of customers who refer) | > 5% | ReferralCandy dashboard | | Referral conversion rate | > 15% of clicks convert | App analytics | | K-factor (share rate × conversion rate) | 0.3–0.5 = strong; 1.0+ = viral | Calculate from share rate × conversion rate | | Revenue from referred customers | 10–20% of total new customer revenue | App analytics | | Cost per acquisition via referral | Usually 40–60% below paid CAC | Reward cost ÷ referred orders |
| Problem | Solution | |---------|----------| | Self-referral fraud (customer creates new account to get referee discount) | Enable IP-based duplicate detection; flag same-IP conversions for manual review (ReferralCandy has this built in) | | Referral codes shared publicly on coupon sites | Make codes unique per referrer so bulk sharing is detectable; ReferralCandy monitors velocity automatically | | Referrer reward given before order ships | Always delay referrer reward by 7+ days; use the app's built-in reward delay setting | | Low share rate despite good rewards | Reduce friction — use pre-filled share messages; show the referral widget immediately post-purchase | | Referred customers do not convert | Increase the referee incentive — 15% off typically outperforms 10% off for first-order conversion |
tools
Let shoppers save products to a wishlist, share it with friends, and get notified when saved items come back in stock or drop in price
development
Build a themeable storefront with design tokens and CSS custom properties that supports white-labeling, multi-brand variants, and dark mode
development
Speed up product discovery with instant search suggestions, fuzzy typo matching, and category-aware results powered by Algolia or Elasticsearch
development
Build a mobile-first storefront with thumb-friendly navigation, sticky add-to-cart buttons, and touch-optimized components for high mobile conversion