{Array.from({ length: 4 }).map((_, i) => (

))}

); } if (error || !data) { return

Could not load referral stats. Try refreshing.

; } ``` -------------------------------- ### Coolify Environment Variables for RefearnApp Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/opensource-alternative-to-rewardful.mdx Required environment variables for deploying RefearnApp in Coolify. Set NEXT_PUBLIC_APP_URL to your tracking subdomain and DATABASE_URL to your PostgreSQL connection string. ```env NEXT_PUBLIC_APP_URL=https://tracking.yourdomain.com DATABASE_URL=postgresql://user:password@your-postgres-host:5432/refearn ``` -------------------------------- ### SQL Schema for Affiliate Commissions and Indexes Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx Defines the affiliate_commissions table and supporting indexes for tracking recurring commissions. Use this schema to store commission events linked to affiliates and Stripe invoices, with indexes on affiliate_id and status for efficient queries. ```sql -- Recurring commission events CREATE TABLE affiliate_commissions ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), affiliate_id UUID NOT NULL REFERENCES affiliates(id), stripe_invoice_id TEXT UNIQUE NOT NULL, amount_cents INTEGER NOT NULL, commission_cents INTEGER NOT NULL, type TEXT NOT NULL DEFAULT 'recurring', status TEXT NOT NULL DEFAULT 'pending', paid_at TIMESTAMPTZ NOT NULL ); CREATE INDEX idx_conversions_affiliate ON affiliate_conversions(affiliate_id); CREATE INDEX idx_commissions_affiliate ON affiliate_commissions(affiliate_id); CREATE INDEX idx_conversions_status ON affiliate_conversions(status); ``` -------------------------------- ### Resolve affiliate from checkout session Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx Resolves affiliate attribution from a completed checkout session. Checks both total_details (for promotion codes applied at checkout) and session metadata (for coupons applied programmatically). Returns affiliateId, couponCodeRecord, and discountAppliedCents if found, otherwise null. ```typescript /** * Resolves affiliate attribution from a completed checkout session. * Checks both total_details (for promotion codes applied at checkout) * and session metadata (for coupons applied programmatically). */ async function resolveAffiliateFromSession(session: Stripe.Checkout.Session): Promise<{ affiliateId: string; couponCodeRecord: { id: string }; discountAppliedCents: number; } | null> { // Path 1: Promotion code applied by user at checkout // Stripe exposes this in session.total_details.breakdown.discounts const expandedSession = await stripe.checkout.sessions.retrieve(session.id, { expand: ['total_details.breakdown.discounts'], }); const discounts = expandedSession.total_details?.breakdown?.discounts ?? []; for (const discount of discounts) { const promoCodeId = (discount.discount as Stripe.Discount).promotion_code; if (!promoCodeId) continue; // Look up the promotion code in our local DB const couponCodeRecord = await db.affiliateCouponCode.findUnique({ where: { stripePromotionCodeId: typeof promoCodeId === 'string' ? promoCodeId : promoCodeId.id, }, }); if (couponCodeRecord) { return { affiliateId: couponCodeRecord.affiliateId, couponCodeRecord: { id: couponCodeRecord.id }, discountAppliedCents: discount.amount ?? 0, }; } } // Path 2: Coupon applied programmatically (not via promotion code) // Fall back to checking the coupon metadata directly if (session.total_details?.breakdown?.discounts) { for (const discount of session.total_details.breakdown.discounts) { const couponId = (discount.discount as Stripe.Discount).coupon?.id; if (!couponId) continue; const couponCodeRecord = await db.affiliateCouponCode.findFirst({ where: { stripeCouponId: couponId }, }); if (couponCodeRecord) { return { affiliateId: couponCodeRecord.affiliateId, couponCodeRecord: { id: couponCodeRecord.id }, discountAppliedCents: discount.amount ?? 0, }; } } } return null; } ``` -------------------------------- ### Create Stripe Checkout session with affiliate cookie Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx Creates a Stripe Checkout session for a subscription, reading the affiliate reference from the request cookie and preparing it as session metadata. Uses the Stripe API version '2024-11-20' and environment variables for the secret key and price ID. The success URL includes the checkout session ID placeholder. ```ts import { NextRequest, NextResponse } from 'next/server'; import Stripe from 'stripe'; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2024-11-20', }); export async function POST(request: NextRequest): Promise { // Read the affiliate cookie from the incoming request const affiliateRef = request.cookies.get('affiliate_ref')?.value ?? null; const sessionParams: Stripe.Checkout.SessionCreateParams = { mode: 'subscription', line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }], success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`, cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`, }; // ... create checkout session and return redirect } ``` -------------------------------- ### RefTracker component to capture referral param Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/affiliate-program-nextjs.mdx A client component that reads the 'ref' query parameter using useSearchParams and stores it in a cookie named 'affiliate_ref' with a 30-day expiry, sameSite lax, and secure flag in production. Must be wrapped in a Suspense boundary in the root layout to avoid breaking server-side rendering. ```tsx 'use client'; import { useSearchParams } from 'next/navigation'; import { useEffect } from 'react'; import Cookies from 'js-cookie'; export function RefTracker() { const searchParams = useSearchParams(); useEffect(() => { const ref = searchParams.get('ref'); if (ref) { Cookies.set('affiliate_ref', ref, { expires: 30, sameSite: 'lax', secure: process.env.NODE_ENV === 'production', }); } }, [searchParams]); return null; } ``` -------------------------------- ### Referral Stats Dashboard Component Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx Renders a dashboard displaying referral statistics: total clicks, signups, conversions, and pending earnings. It highlights the pending earnings stat and lists recent conversions with their status and commission amounts. ```jsx const stats = [ { label: 'Clicks', value: data.totalClicks.toLocaleString() }, { label: 'Signups', value: data.totalSignups.toLocaleString() }, { label: 'Conversions', value: data.totalConversions.toLocaleString() }, { label: 'Pending Earnings', value: formatCents(data.pendingCommissionCents), highlight: true }, ]; return (

{stats.map((stat) => (

{stat.label}

{stat.value}

))}

{data.recentConversions.length > 0 && (

Recent Conversions

{data.recentConversions.map((conversion) => (

{formatCents(conversion.amountCents)} sale

{new Date(conversion.convertedAt).toLocaleDateString()}

+{formatCents(conversion.commissionCents)}

{conversion.status}

))}

)}

); }` } ] } ] }``` ``` -------------------------------- ### Calculate Coupon Discount Amount from Invoice Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx Calculates the total discount amount applied to an invoice by summing discount amounts across all line items. Used to determine the discount for affiliate commission calculations. ```TypeScript async function getCouponDiscountAmount(invoice: Stripe.Invoice): Promise { return Math.abs( invoice.lines.data.reduce((total, line) => { const discountAmounts = line.discount_amounts ?? []; return total + discountAmounts.reduce((sum, d) => sum + d.amount, 0); }, 0), ); } ``` -------------------------------- ### Push schema to Postgres database Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx Use this command to push the schema layout structures directly to your Postgres database. This is typically done in development or when you need to update the database schema without running migrations. ```bash pnpm db:push ``` -------------------------------- ### Create Single-Use Promotion Code Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/stripe-coupon-affiliate-tracking.mdx Creates a single-use Stripe promotion code with max_redemptions set to 1, enforcing server-side. Includes affiliate metadata for tracking. ```TypeScript const promotionCode = await stripe.promotionCodes.create({ coupon: coupon.id, code: `${affiliateSlug.toUpperCase()}-${crypto.randomUUID().slice(0, 8).toUpperCase()}`, max_redemptions: 1, // Stripe enforces this server-side metadata: { affiliate_id: affiliateId, affiliate_slug: affiliateSlug }, }); ``` -------------------------------- ### Capture affiliate reference with first-click attribution Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx Captures the affiliate reference from URL query parameters and stores it in a cookie with a 30-day expiration. Uses first-click attribution, so the cookie is not overwritten if it already exists. The slug is validated against a pattern allowing alphanumeric characters and hyphens. ```typescript // Simplified attribution logic — runs when a visitor lands export function captureAffiliateRef(searchParams: URLSearchParams): void { const ref = searchParams.get('ref'); if (!ref || !isValidSlug(ref)) return; // Only set on first touch — first-click attribution if (document.cookie.includes('affiliate_ref=')) return; const maxAge = 60 * 60 * 24 * 30; // 30 days document.cookie = `affiliate_ref=${encodeURIComponent(ref)}; max-age=${maxAge}; path=/; SameSite=Lax`; } function isValidSlug(slug: string): boolean { return /^[a-zA-Z0-9][a-zA-Z0-9-]{1,39}$/.test(slug); } ``` -------------------------------- ### Commented Hosts Entries Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md Comment out the hosts entries to access production platforms when Caddy is not running. ```text # 127.0.0.1 refearnapp.com # 127.0.0.1 xyz.refearnapp.com ``` -------------------------------- ### ReferralTracker component with cookie-based attribution Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx Tracks referral links by reading the 'ref' query parameter, validating it with a slug pattern, and setting a cookie for 30 days. Uses first-click attribution, so it doesn't overwrite an existing cookie. Must be wrapped in Suspense in the App Router to avoid static rendering errors. ```typescript import { useEffect } from 'react'; import { useSearchParams } from 'next/navigation'; const COOKIE_NAME = 'affiliate_ref'; const COOKIE_MAX_AGE = 60 * 60 * 24 * 30; // 30 days function isValidSlug(slug: string): boolean { return /^[a-zA-Z0-9][a-zA-Z0-9-]{1,39}$/.test(slug); } function getCookie(name: string): string | null { const match = document.cookie.match(new RegExp(`(^| )${name}=([^;]+)`)); return match ? decodeURIComponent(match[2]) : null; } function setCookie(name: string, value: string, maxAge: number): void { document.cookie = [ `${name}=${encodeURIComponent(value)}`, `max-age=${maxAge}`, 'path=/', 'SameSite=Lax', process.env.NODE_ENV === 'production' ? 'Secure' : '', ] .filter(Boolean) .join('; '); } export function ReferralTracker() { const searchParams = useSearchParams(); useEffect(() => { const ref = searchParams.get('ref'); if (!ref || !isValidSlug(ref)) return; // First-click attribution — don't overwrite if already set if (getCookie(COOKIE_NAME)) return; setCookie(COOKIE_NAME, ref, COOKIE_MAX_AGE); }, [searchParams]); return null; } ``` -------------------------------- ### Stripe Checkout Session Creation (app/api/checkout/route.ts) Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/affiliate-program-nextjs.mdx API route that creates a Stripe Checkout session for a subscription. It reads the affiliate_ref cookie, passes it as metadata to the session, and returns the session URL in the response. ```TypeScript import { NextRequest, NextResponse } from 'next/server'; import Stripe from 'stripe'; const stripe = new Stripe( process.env.STRIPE_SECRET_KEY!, { apiVersion: '2024-04-10', } ); export async function POST(request: NextRequest) { const affiliateRef = request.cookies.get('affiliate_ref')?.value ?? null; const session = await stripe.checkout.sessions.create({ mode: 'subscription', line_items: [ { price: process.env.STRIPE_PRICE_ID!, quantity: 1, }, ], success_url: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`, cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`, metadata: { affiliate_ref: affiliateRef ?? '', }, }); return NextResponse.json({ url: session.url, }); } ``` -------------------------------- ### Stripe webhook handler for commission recording Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx Handles Stripe webhook events to record affiliate commissions. Verifies the signature, processes checkout.session.completed for initial conversions, and handles invoice.payment_succeeded for recurring commissions. ```TypeScript import { NextRequest, NextResponse } from 'next/server'; import Stripe from 'stripe'; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2024-11-20', }); export async function POST(request: NextRequest): Promise { const body = await request.text(); const sig = request.headers.get('stripe-signature'); if (!sig) return NextResponse.json({ error: 'No signature' }, { status: 400 }); let event: Stripe.Event; try { event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!); } catch { return NextResponse.json({ error: 'Invalid signature' }, { status: 400 }); } // Initial conversion if (event.type === 'checkout.session.completed') { const session = event.data.object as Stripe.Checkout.Session; const ref = session.metadata?.affiliate_ref; if (ref && session.amount_total) { await db.affiliateConversion.create({ data: { affiliateSlug: ref, stripeSessionId: session.id, stripeCustomerId: session.customer as string, amountCents: session.amount_total, commissionCents: Math.floor(session.amount_total * 0.2), // 20% commission status: 'pending', convertedAt: new Date(), }, }); } } // Recurring commissions if (event.type === 'invoice.payment_succeeded') { const invoice = event.data.object as Stripe.Invoice; const sub = await stripe.subscriptions.retrieve(invoice.subscription as string); const ref = sub.metadata?.affiliate_ref; if (ref && invoice.amount_paid) { await db.affiliateCommission.create({ data: { affiliateSlug: ref, stripeInvoiceId: invoice.id, amountCents: invoice.amount_paid, commissionCents: Math.floor(invoice.amount_paid * 0.2), type: 'recurring', status: 'pending', paidAt: new Date(), }, }); } } return NextResponse.json({ received: true }); } ``` -------------------------------- ### ReferralLinkCard component to display and copy referral link Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx Displays the referral link and provides a copy button. Uses the useReferralLink hook. Shows a 'Copied!' confirmation for 2 seconds after copying. ```tsx // components/ReferralLinkCard.tsx 'use client'; import { useState } from 'react'; import { useReferralLink } from '@/hooks/useReferralLink'; export function ReferralLinkCard() { const { referralLink } = useReferralLink(); const [copied, setCopied] = useState(false); async function handleCopy() { if (!referralLink) return; await navigator.clipboard.writeText(referralLink); setCopied(true); setTimeout(() => setCopied(false), 2000); } if (!referralLink) return null; return (

Your Referral Link

Share this link and earn 20% of every customer you refer — recurring.


              {referralLink}

); } ``` -------------------------------- ### generateReferralSlug function using nanoid Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/how-to-build-a-referral-system-in-react.mdx Generates a referral slug. Uses a custom alphabet without ambiguous characters. If a username is provided and valid, it uses a cleaned version of it; otherwise, it falls back to a random ID. ```typescript // lib/referral/generate-slug.ts import { customAlphabet } from 'nanoid'; // Alphanumeric only, no ambiguous characters (0, O, I, l) const generateId = customAlphabet('23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz', 8); export function generateReferralSlug(username?: string): string { if (username) { // Use username if available and valid, fall back to random ID const cleaned = username.toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 20); if (cleaned.length >= 3) return cleaned; } return generateId(); } ``` -------------------------------- ### Attach affiliate reference to Stripe session and subscription Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/self-hosted-affiliate-tracking-software.mdx Attaches the affiliate reference to both the session metadata and subscription data so it is available in webhook events. This is required for tracking both one-time conversions and recurring commissions. ```TypeScript if (affiliateRef) { // Attach to session — readable in checkout.session.completed webhook sessionParams.metadata = { affiliate_ref: affiliateRef }; // Attach to subscription — readable on every invoice for recurring commissions sessionParams.subscription_data = { metadata: { affiliate_ref: affiliateRef }, }; } const session = await stripe.checkout.sessions.create(sessionParams); return NextResponse.json({ url: session.url }); } ``` -------------------------------- ### Full Ref Capture with Validation (middleware.ts) Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/affiliate-program-nextjs.mdx Enhanced middleware that validates the referral parameter using a regex pattern before setting the cookie. It also defines constants for the cookie name and max age, and sets the cookie with additional security options like httpOnly and path. ```TypeScript import { NextRequest, NextResponse } from 'next/server'; const REF_COOKIE = 'affiliate_ref'; const REF_MAX_AGE = 60 * 60 * 24 * 30; function isValidRef(ref: string): boolean { return /^[a-zA-Z0-9-]{3,32}$/.test(ref); } export function middleware(request: NextRequest) { const response = NextResponse.next(); const ref = request.nextUrl.searchParams.get('ref'); if ( ref && isValidRef(ref) && !request.cookies.has(REF_COOKIE) ) { response.cookies.set(REF_COOKIE, ref, { maxAge: REF_MAX_AGE, httpOnly: true, sameSite: 'lax', secure: process.env.NODE_ENV === 'production', path: '/', }); } return response; } ``` -------------------------------- ### Dashboard Redirection URL Source: https://github.com/zak123dsfdf/refearnapp/blob/main/CONTRIBUTING.md Set this environment variable in apps/dashboard/.env to the ngrok tunnel URL for local tracking redirects. ```text NEXT_PUBLIC_REDIRECTION_URL=https://your-tunnel-id.ngrok-free.app ``` -------------------------------- ### Middleware to intercept inbound request edge Source: https://github.com/zak123dsfdf/refearnapp/blob/main/apps/landing-page/src/content/blog/affiliate-program-nextjs.mdx An alternative to the client component approach, using Next.js middleware to intercept the inbound request edge directly. This is Option B for capturing the referral param with zero client JavaScript. ```ts import { NextRequest, NextResponse } from 'next/server'; ```