DEV Community: Zekariyas Berihun

The Best Open Source Alternative to Rewardful: Why Self-Hosting Wins

Zekariyas Berihun — Wed, 03 Jun 2026 06:20:52 +0000

Rewardful starts at $49/month. That's before a single affiliate has driven a single dollar of revenue. At their Growth tier, you're paying more — and as your MRR climbs, so does your plan requirement. The pricing is structured to extract more from you precisely when your affiliate program is working. That's not a partnership. That's a toll booth on your own growth.

The developer community has already solved this pattern in adjacent categories. You don't pay Mixpanel when you can self-host PostHog. You don't pay a managed auth vendor when you can run Supabase. You don't pay for a black-box analytics SaaS when Plausible runs on your own VPS for the cost of a DigitalOcean droplet. The same logic applies to affiliate tracking — and the tooling now exists to act on it.

The core engineering argument for self-hosting affiliate tracking:

100% data ownership. Your conversion events, click logs, affiliate relationships, and commission history live in your own Postgres database. No API rate limits. No export quotas. No support ticket to access your own data. Direct SQL, any time.
No third-party scripts on your frontend. Rewardful injects tracking JavaScript from an external domain. That script is a dependency you don't control — it can change, slow down, or get blocked without warning.
Attribution tables you can JOIN against anything. When your affiliate data is in your own schema, cross-referencing conversion rates against plan type, churn cohort, or acquisition channel is a query, not a feature request.
Zero compounding cost. A Docker container on infrastructure you're already running costs nothing incremental. The affiliate program that drives $50K MRR costs the same to run as the one driving $500. RefearnApp is the open-source, self-hostable affiliate management platform built for exactly this use case — designed for developer-founders who want Rewardful's feature set without Rewardful's pricing model or data policies.

Feature Breakdown: Rewardful vs. RefearnApp

License: Rewardful is proprietary and closed-source. RefearnApp is AGPL-3.0 — full source access, fork it, modify it freely.
Infrastructure: Rewardful is a cloud-only managed black box. RefearnApp self-hosts via Docker, Coolify, or any VPS you already run.
Data Access: Rewardful locks your data behind a dashboard UI and rate-limited API. RefearnApp gives you full Postgres/SQL access — your schema, your queries, any time.
Source Code Access: Rewardful gives you none. RefearnApp is completely open — read it, extend it, modify it without asking anyone.
Ad-Blocker Vulnerability: Rewardful's external tracking script is blocked by Brave, uBlock Origin, and Safari ITP. RefearnApp runs on your own domain as a first-party service — nothing to block.
Stripe Integration: Rewardful manages this for you, as a black box. RefearnApp's Stripe integration — webhooks, metadata, coupon tracking — is self-managed and fully transparent.
Coupon Code Tracking: Rewardful only offers this on higher pricing tiers. RefearnApp includes it out of the box at every level.
Affiliate Portal: Rewardful's portal is hosted and branded by them. RefearnApp's is self-hosted and fully customizable to match your product.
Payout Management: Rewardful manages payouts for you through their platform. RefearnApp gives you admin-controlled approve/decline at the affiliate level.
Data Portability: Rewardful gives you CSV exports only. RefearnApp gives you direct database access — no export process needed.
Vendor Lock-in: Rewardful is high lock-in — your links, data, and logic live on their infrastructure. RefearnApp is zero lock-in — everything runs on infrastructure you own.
Cost: Rewardful runs $49–$299+/month and scales against you as revenue grows. RefearnApp is free to self-host — pay only for your own infra. This isn't a marketing exercise. It's the architectural decision tree. If any point in the left column is a hard requirement for your infrastructure philosophy, Rewardful is the wrong tool. If full control over every point matters — and for most developer-founders, it does — self-hosting is the only rational choice.

Bypassing Third-Party Tracking Blockers

This is the technical problem that closed-source affiliate platforms don't talk about, because they can't fix it without fundamentally changing their architecture.

When you install Rewardful, it loads a tracking script from an external domain — typically something like r.stripe.com or rewardful.com. That script sets cookies, fires conversion beacons, and handles attribution. It's also exactly what ad-blockers and privacy-focused browsers are designed to intercept.

What gets blocked, and why:

uBlock Origin maintains a filter list of known tracking domains. External affiliate scripts are categorically blocked — not because of specific behavior, but because of domain reputation.
Brave Browser blocks cross-site trackers and third-party cookies by default. A script loaded from rewardful.com on your domain is a cross-site request. It gets blocked before it executes.
Safari's Intelligent Tracking Prevention (ITP) caps third-party cookie lifetime at 7 days and blocks cross-site tracking entirely in some configurations. An affiliate who converted after clicking a link 10 days ago is invisible to platforms relying on third-party cookies.
Firefox Enhanced Tracking Protection blocks known tracker domains using the Disconnect.me list. Rewardful's tracking endpoints appear on it. For a general consumer SaaS, this might mean losing 15–20% of attributions. For a developer-focused product — exactly the audience most likely to run ad-blockers — that number is closer to 30–40%. You're systematically undercounting the contributions of the affiliates most likely to drive high-quality developer traffic.

How self-hosting fixes this at the infrastructure level:

When RefearnApp runs on your own infrastructure, the tracking layer operates entirely in a first-party context. Your Cloudflare Worker runs on tracking.yourdomain.com. Your API routes are on yourdomain.com. There is no external domain for a filter list to block. From the browser's perspective, every request is to a domain the user already trusts — yours.

# Third-party (blocked by Brave, uBlock, Safari ITP)
https://api.rewardful.com/track?ref=affiliate123

# First-party (treated identically to your own API)
https://tracking.yourdomain.com/track?ref=affiliate123

The second URL is indistinguishable from your own backend infrastructure. No browser blocks it. No ad-blocker flags it. No ITP policy expires it. You capture 100% of conversions that Rewardful would have silently missed.

RefearnApp's tracking layer is built on Cloudflare Workers — running at the edge, globally distributed, and operating on your own domain from day one.

Core Tech Stack Alignment

The reason most self-hosted tools fail in practice isn't the concept — it's the implementation stack. A tool built on a framework you don't use, with an ORM you don't know, backed by a database you're not running, creates more operational overhead than it saves.

RefearnApp is built on the stack that developer-founders building in 2025 are already running:

Frontend & Dashboard — Next.js (App Router) + TypeScript. The same framework as your SaaS — no context switching, familiar routing and data patterns throughout.
Data Fetching — TanStack Query. Type-safe server state management, optimistic updates, and background revalidation out of the box.
ORM & Schema — Drizzle ORM. TypeScript-native, schema-as-code, migration-first — your affiliate schema is version-controlled alongside your product schema.
Database — PostgreSQL. The database you're already running. Affiliate tables live in the same cluster as your product tables.
Tracking Layer — Cloudflare Workers (Edge). Sub-millisecond click logging globally, runs on your domain, zero cold starts.
Caching & Queuing — Upstash Redis. Serverless-compatible, edge-ready rate limiting and queue processing.
Deployment — Docker + Coolify. One-command setup, runs alongside your existing containerized services. What this means in practice:

When you need custom commission logic — say, higher rates for affiliates who drive annual plan conversions versus monthly — we implement it in a TypeScript function and ship it. You get the update, not a feature request form.

When you want to cross-reference affiliate conversion rate against user churn at 90 days, you JOIN affiliate_conversions ON stripe_customer_id against your own subscriptions table. It's a SQL query you can run in your database client in 30 seconds.

When a new Stripe webhook event becomes relevant to your affiliate flow, we add the handler and push it. You pull the update and redeploy. No waiting on a closed-source vendor's roadmap.

The stack alignment isn't a marketing bullet point. It's the difference between infrastructure that evolves with your program and infrastructure you're locked out of the moment you need something it doesn't do yet.

For a deeper look at how affiliate tracking integrates with your existing Next.js and Stripe setup, see our guides on building an affiliate program in Next.js and tracking Stripe coupons for affiliates.

Deployment Guide

Getting RefearnApp live is straightforward — Docker, Coolify, or any VPS with a Postgres instance. Rather than duplicate the setup steps here, the full deployment guide with environment variable reference, Stripe webhook configuration, and Cloudflare Worker setup is in the docs:

→ RefearnApp Deployment Docs

Take Control of Your Affiliate Data

RefearnApp is fully open-source, self-hostable, and AGPL-3.0 licensed. You can deploy it completely free on your own infrastructure using Coolify or check out our direct paths:

Developer Choice: Read Deployment Docs or ⭐ Star the Repo to run it on your own VPS via Coolify with 100% data ownership.
Production Ready: Try Managed Cloud to get up and running instantly with a fully turnkey, zero-config deployment.

How to Track Stripe Coupons for Affiliates: A Complete Technical Guide

Zekariyas Berihun — Mon, 01 Jun 2026 10:32:56 +0000

Link-based affiliate tracking is straightforward: capture a ?ref= param, set a cookie, read it at checkout. The mechanics are well-documented and the failure modes are predictable.

Coupon-based affiliate tracking is a different problem entirely. There are no referral URLs. No cookies. No client-side JavaScript involved in the attribution. A user finds a promo code in a YouTube description, navigates directly to your pricing page, types it in at checkout, and completes the purchase. The entire attribution chain lives inside Stripe — and the only way to capture it is server-side, via webhooks, after the payment is already confirmed.

If you wire this up wrong, you lose conversions silently. No error. No log. Just a commission that never gets recorded.

This guide walks through the full implementation: schema design, Stripe object metadata, webhook parsing, and the edge cases that will burn you in production if you skip them.

Why Coupon Tracking Is Architecturally Different from Link Tracking

With link-based tracking, the attribution happens before the payment:

User clicks affiliate link → cookie set → checkout → webhook confirms
With coupon-based tracking, the attribution happens during the payment, and you only learn about it after:
User navigates directly → types promo code at checkout → payment completes → webhook fires → you parse the coupon from the event
This distinction matters because:

There's no pre-checkout state to inspect. You can't read a cookie or a session variable. The coupon the user typed is an opaque string until Stripe tells you about it.
The webhook is your only source of truth. If your webhook handler is wrong, buggy, or down during the event, the attribution is gone.
The mapping from coupon code to affiliate must be server-side. You cannot do this lookup in the browser.

The Database & Metadata Architecture

You need two things to make coupon tracking work cleanly:

A local mapping table — links your affiliate IDs to their Stripe promotion code IDs
Metadata on the Stripe Coupon/Promotion Code object — so the affiliate ID travels with the Stripe object and is readable in webhook events without an extra DB round-trip ### Local Mapping Table

-- Affiliates table (you likely already have this)
CREATE TABLE affiliates (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug            TEXT UNIQUE NOT NULL,
  name            TEXT NOT NULL,
  email           TEXT UNIQUE NOT NULL,
  commission_rate NUMERIC(5,4) NOT NULL DEFAULT 0.20,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- One row per promotion code assigned to an affiliate
-- An affiliate can have multiple codes (e.g., different campaigns)
CREATE TABLE affiliate_coupon_codes (
  id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  affiliate_id          UUID NOT NULL REFERENCES affiliates(id) ON DELETE CASCADE,
  stripe_coupon_id      TEXT NOT NULL,           -- e.g., "SUMMER20"
  stripe_promotion_code_id TEXT,                 -- e.g., "promo_1ABC..."
  code                  TEXT NOT NULL,           -- Human-readable code, e.g., "ZAK20"
  discount_type         TEXT NOT NULL,           -- 'percentage' | 'fixed'
  discount_value        NUMERIC(10,2) NOT NULL,  -- e.g., 20.00 (%) or 10.00 ($)
  max_redemptions       INTEGER,                 -- NULL = unlimited
  times_redeemed        INTEGER NOT NULL DEFAULT 0,
  active                BOOLEAN NOT NULL DEFAULT true,
  created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Conversion events attributed via coupon
CREATE TABLE affiliate_coupon_conversions (
  id                       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  affiliate_id             UUID NOT NULL REFERENCES affiliates(id),
  coupon_code_id           UUID NOT NULL REFERENCES affiliate_coupon_codes(id),
  stripe_session_id        TEXT UNIQUE NOT NULL,
  stripe_customer_id       TEXT NOT NULL,
  stripe_subscription_id   TEXT,                -- NULL for one-time payments
  amount_cents             INTEGER NOT NULL,
  discount_applied_cents   INTEGER NOT NULL DEFAULT 0,
  commission_cents         INTEGER NOT NULL,
  status                   TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | paid | reversed
  converted_at             TIMESTAMPTZ NOT NULL,
  paid_at                  TIMESTAMPTZ
);

CREATE INDEX idx_coupon_codes_affiliate ON affiliate_coupon_codes(affiliate_id);
CREATE INDEX idx_coupon_codes_stripe_coupon ON affiliate_coupon_codes(stripe_coupon_id);
CREATE INDEX idx_coupon_codes_promo_id ON affiliate_coupon_codes(stripe_promotion_code_id);
CREATE INDEX idx_coupon_conversions_affiliate ON affiliate_coupon_conversions(affiliate_id);
CREATE INDEX idx_coupon_conversions_status ON affiliate_coupon_conversions(status);

Creating the Stripe Coupon with Affiliate Metadata

When you create a coupon for an affiliate, embed the affiliate ID directly into the Stripe object's metadata field. This is critical — it means your webhook handler can attribute the sale without a DB lookup on the hot path.

// lib/stripe/create-affiliate-coupon.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-11-20',
});

interface CreateAffiliateCouponParams {
  affiliateId: string;
  affiliateSlug: string;
  code: string;                          // e.g., "ZAK20"
  percentOff?: number;                   // e.g., 20 for 20% off
  amountOff?: number;                    // in cents, e.g., 1000 for $10 off
  currency?: string;                     // required if amountOff is set
  maxRedemptions?: number;               // omit for unlimited
  durationInMonths?: number;             // for 'repeating' duration
}

export async function createAffiliateCoupon(
  params: CreateAffiliateCouponParams,
): Promise<{ couponId: string; promotionCodeId: string }> {
  const {
    affiliateId,
    affiliateSlug,
    code,
    percentOff,
    amountOff,
    currency = 'usd',
    maxRedemptions,
    durationInMonths,
  } = params;

  if (!percentOff && !amountOff) {
    throw new Error('Either percentOff or amountOff must be provided');
  }

  // Step 1: Create the underlying Stripe Coupon
  const coupon = await stripe.coupons.create({
    ...(percentOff ? { percent_off: percentOff } : {}),
    ...(amountOff ? { amount_off: amountOff, currency } : {}),
    duration: durationInMonths ? 'repeating' : 'once',
    ...(durationInMonths ? { duration_in_months: durationInMonths } : {}),
    metadata: {
      affiliate_id: affiliateId,
      affiliate_slug: affiliateSlug,
      source: 'refearnapp',
    },
  });

  // Step 2: Create a Promotion Code on top of the Coupon
  // Promotion Codes are what users actually type at checkout
  const promotionCode = await stripe.promotionCodes.create({
    coupon: coupon.id,
    code,                                // The human-readable code, e.g., "ZAK20"
    ...(maxRedemptions ? { max_redemptions: maxRedemptions } : {}),
    metadata: {
      affiliate_id: affiliateId,
      affiliate_slug: affiliateSlug,
      source: 'refearnapp',
    },
  });

  return {
    couponId: coupon.id,
    promotionCodeId: promotionCode.id,
  };
}

Why metadata on both the Coupon and the Promotion Code?

Stripe's data model has a subtle distinction: a Coupon is the discount rule (20% off), while a Promotion Code is the code users type (ZAK20). One Coupon can have multiple Promotion Codes. In the webhook, you'll receive the Promotion Code ID — but depending on how you query the event, you may only have the Coupon ID. Putting the affiliate metadata on both ensures you can recover the attribution either way.

The Webhook Implementation

This is the critical path. Every production edge case lives here.

// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import { db } from '@/lib/db';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-11-20',
});

export async function POST(request: NextRequest): Promise<NextResponse> {
  const body = await request.text();
  const signature = request.headers.get('stripe-signature');

  if (!signature) {
    return NextResponse.json({ error: 'Missing stripe-signature header' }, { status: 400 });
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!,
    );
  } catch (err) {
    console.error('Webhook signature verification failed:', err);
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  try {
    switch (event.type) {
      case 'checkout.session.completed':
        await handleCheckoutCompleted(event.data.object as Stripe.Checkout.Session);
        break;

      case 'invoice.payment_succeeded':
        await handleInvoicePaymentSucceeded(event.data.object as Stripe.Invoice);
        break;

      default:
        // Acknowledge unhandled events — never return 4xx for unknown types
        break;
    }
  } catch (err) {
    // Return 500 so Stripe retries the webhook
    console.error(`Error processing webhook ${event.type}:`, err);
    return NextResponse.json({ error: 'Internal processing error' }, { status: 500 });
  }

  return NextResponse.json({ received: true });
}

async function handleCheckoutCompleted(
  session: Stripe.Checkout.Session,
): Promise<void> {
  // Guard: only process paid sessions
  if (session.payment_status !== 'paid') return;

  // Guard: idempotency — don't double-record the same session
  const existing = await db.affiliateCouponConversion.findUnique({
    where: { stripeSessionId: session.id },
  });
  if (existing) return;

  // Extract the applied promotion code from the session
  const affiliateAttribution = await resolveAffiliateFromSession(session);
  if (!affiliateAttribution) return; // No coupon applied, or not an affiliate code

  const { affiliateId, couponCodeRecord, discountAppliedCents } = affiliateAttribution;

  // Fetch the affiliate to get their commission rate
  const affiliate = await db.affiliate.findUnique({
    where: { id: affiliateId },
  });
  if (!affiliate) return;

  const commissionCents = Math.floor(
    (session.amount_total ?? 0) * Number(affiliate.commissionRate),
  );

  await db.affiliateCouponConversion.create({
    data: {
      affiliateId,
      couponCodeId: couponCodeRecord.id,
      stripeSessionId: session.id,
      stripeCustomerId: session.customer as string,
      stripeSubscriptionId: session.subscription as string | null,
      amountCents: session.amount_total ?? 0,
      discountAppliedCents,
      commissionCents,
      status: 'pending',
      convertedAt: new Date(),
    },
  });

  // Increment the redemption counter on the local record
  await db.affiliateCouponCode.update({
    where: { id: couponCodeRecord.id },
    data: { timesRedeemed: { increment: 1 } },
  });
}

async function handleInvoicePaymentSucceeded(
  invoice: Stripe.Invoice,
): Promise<void> {
  // Only handle recurring subscription invoices, not the initial one
  // (the initial invoice is already captured via checkout.session.completed)
  if (invoice.billing_reason !== 'subscription_cycle') return;
  if (!invoice.subscription) return;

  // Look up the original conversion to find the affiliate
  const originalConversion = await db.affiliateCouponConversion.findFirst({
    where: { stripeSubscriptionId: invoice.subscription as string },
    orderBy: { convertedAt: 'asc' },
    include: { affiliate: true, couponCode: true },
  });

  if (!originalConversion) return;

  // Check if the coupon still applies to this invoice
  // Stripe stops applying coupons after their duration expires
  const discountApplied = (invoice.discount?.coupon?.id)
    ? await getCouponDiscountAmount(invoice)
    : 0;

  const commissionCents = Math.floor(
    invoice.amount_paid * Number(originalConversion.affiliate.commissionRate),
  );

  await db.affiliateCouponConversion.create({
    data: {
      affiliateId: originalConversion.affiliateId,
      couponCodeId: originalConversion.couponCodeId,
      stripeSessionId: `invoice_${invoice.id}`, // Synthetic ID for recurring events
      stripeCustomerId: invoice.customer as string,
      stripeSubscriptionId: invoice.subscription as string,
      amountCents: invoice.amount_paid,
      discountAppliedCents: discountApplied,
      commissionCents,
      status: 'pending',
      convertedAt: new Date(),
    },
  });
}

/**
 * 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;
}

async function getCouponDiscountAmount(invoice: Stripe.Invoice): Promise<number> {
  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),
  );
}

Edge Cases to Handle in Production

1. Idempotency: Stripe Retries Webhooks

Stripe will retry a webhook up to 3 days if it doesn't receive a 2xx response. This means your handler will be called multiple times for the same event during outages or deploys. The idempotency guard at the top of handleCheckoutCompleted (checking for an existing record by stripeSessionId) prevents double-recording. Never skip this.

// Always check before writing
const existing = await db.affiliateCouponConversion.findUnique({
  where: { stripeSessionId: session.id },
});
if (existing) return; // Idempotent: already processed

2. Multi-Use vs. Single-Use Promotion Codes

Multi-use codes (shared publicly): one code used by many customers. Commission goes to the affiliate who owns the code. Standard case, handled by the implementation above.

Single-use codes (generated per-customer): one code per user, often used for personalized discounts or referral bonuses. If you generate these at scale, make sure your affiliate_coupon_codes table can handle the volume and your lookup index on stripe_promotion_code_id stays performant.

For single-use codes, enforce max_redemptions: 1 when creating the Promotion Code in Stripe:

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 },
});

3. Subscription Renewals vs. One-Time Payments

The checkout.session.completed event fires once per initial purchase. For subscriptions, subsequent renewals fire invoice.payment_succeeded with billing_reason: 'subscription_cycle'.

Key distinction: the first invoice for a subscription fires both checkout.session.completed AND invoice.payment_succeeded (with billing_reason: 'subscription_create'). If you handle both naively, you'll double-record the initial conversion. The guard billing_reason !== 'subscription_cycle' in handleInvoicePaymentSucceeded prevents this — only recurring renewals trigger that handler.

4. Coupon Duration vs. Commission Duration

A Stripe coupon with duration: 'once' only applies the discount to the first invoice. Your affiliate still deserves commissions on subsequent renewals even after the discount expires — unless your program explicitly limits commission windows. Handle this by looking up the original conversion via stripeSubscriptionId on every renewal, regardless of whether the coupon is still active on that invoice.

5. Refunds and Reversals

When a customer is refunded, listen to the charge.refunded event and mark the corresponding conversion as reversed:

case 'charge.refunded': {
  const charge = event.data.object as Stripe.Charge;
  if (charge.payment_intent) {
    // Find the session associated with this payment intent
    const sessions = await stripe.checkout.sessions.list({
      payment_intent: charge.payment_intent as string,
    });
    if (sessions.data[0]) {
      await db.affiliateCouponConversion.updateMany({
        where: { stripeSessionId: sessions.data[0].id },
        data: { status: 'reversed' },
      });
    }
  }
  break;
}

Never pay out commissions with status: 'pending' or status: 'reversed'. Only pay status: 'approved'.

The Build-vs-Deploy Calculation for Coupon Tracking

Component	DIY Effort
Stripe coupon + promotion code creation	~2 hours
Local DB schema + migrations	~1 hour
Webhook handler with idempotency	~3 hours
Recurring commission attribution	~2 hours
Refund/reversal handling	~1 hour
Affiliate-facing coupon dashboard	40–80 hours
Admin UI to create and assign codes	20–40 hours
Commission reporting per code	20–40 hours

The webhook logic above is a weekend of work. The surrounding infrastructure — the UI to create and assign coupon codes to affiliates, the dashboard where affiliates see their code performance, the commission reporting broken down by code — is where real time goes.

Where RefearnApp Handles This Out of the Box

Building and maintaining this webhook pipeline is the kind of infrastructure work that looks simple until you're debugging a missed attribution at 2am because Stripe changed how it surfaces promotion code IDs in a new API version.

RefearnApp is an open-source, self-hosted affiliate tracking platform that ships coupon code tracking as a built-in feature alongside standard link-based referral tracking.

What's already built:

Coupon code tracking — The Stripe webhook handler, promotion code resolution, and affiliate attribution pipeline described in this post are implemented and maintained in the RefearnApp codebase. You configure it, not build it.
Affiliate portal — Affiliates log into their own dashboard and see performance broken down by their assigned coupon code: redemptions, revenue attributed, commission earned.
Admin coupon management — Create and assign promotion codes to affiliates from the admin UI. No Stripe dashboard hunting required.
Payout tracking — Approve or decline commissions at the affiliate level. Mark payouts as paid. Full commission history per affiliate.
Zero revenue cut — Every dollar of commission goes to your affiliates. RefearnApp takes nothing.
Your database, your schema — Data lives in your own Postgres instance. Direct SQL access. No CSV exports, no vendor lock-in. If you're running both link-based and coupon-based affiliate programs simultaneously (common for SaaS — links for content creators, coupons for podcast sponsors), RefearnApp tracks both attribution paths in a unified dashboard.

For more on how referral link tracking works alongside coupons, see our guides on building an affiliate program in Next.js and self-hosted affiliate tracking software for SaaS.

Summary

Coupon-based affiliate tracking is a pure server-side problem. The key points:

No cookies, no URL params. Attribution lives entirely in the Stripe webhook event.
Metadata on both Coupon and Promotion Code objects ensures you can recover the affiliate ID regardless of which Stripe object surfaces in the event.
Idempotency is non-negotiable. Stripe retries webhooks. Your handler will be called multiple times.
Subscription renewals need separate handling. checkout.session.completed handles the initial conversion; invoice.payment_succeeded with billing_reason: 'subscription_cycle' handles recurring commissions.

- Refunds must reverse commissions. Never pay out on a conversion that's been refunded.

Conclusion & Next Steps

Take Control of Your Affiliate Data

RefearnApp is fully open-source, self-hostable, and AGPL-3.0 licensed. You can deploy it completely free on your own infrastructure using Coolify or check out our direct paths:

Developer Choice: Read Deployment Docs or ⭐ Star the Repo to run it on your own VPS via Coolify with 100% data ownership.
Production Ready: Try Managed Cloud to get up and running instantly with a fully turnkey, zero-config deployment.

Self-Hosted Affiliate Tracking Software for SaaS: Own Your Data, Own Your Growth

Zekariyas Berihun — Sat, 30 May 2026 10:19:42 +0000

You're building a SaaS. You want affiliates. You sign up for a third-party platform, paste in an embed snippet, and your program is live in 20 minutes.

Six months later you decide to switch tools — better pricing, a feature you need, or the platform gets acquired and the product direction changes. You export your CSV. And then you realize what you've actually lost.

The CSV has affiliate names, emails, and a payout history. What it doesn't have: the actual tracking infrastructure. The referral links are dead. The cookie logic lived on their servers. The conversion attribution pipeline is gone. You don't just migrate data — you rebuild from scratch. Every affiliate needs a new link. Every integration needs to be rewired. The "switch" that should take a weekend takes a month.

This is the core problem with third-party affiliate platforms that nobody writes about. It's not just the monthly fee. It's that switching costs compound invisibly until the day you try to leave.

The Real Cost of Third-Party Affiliate Platforms

Your Data Is Theirs Until You Leave

When you run your affiliate program on a closed-source platform, your conversion events, click logs, affiliate relationships, and commission history all live in their database schema. You get access through their UI and, if you're lucky, a reasonably complete API.

The moment you stop paying, access is revoked. The CSV they give you is a snapshot — flat, denormalized, stripped of relational context. You lose:

Click-level attribution data — which specific link, which campaign, which landing page variant drove each conversion
Time-series granularity — daily click and conversion curves that let you spot seasonal patterns or campaign spikes
Custom metadata — any extra fields you attached to affiliate signups or conversion events
The tracking layer itself — the referral link format, the cookie domain, the JavaScript snippet. All of it belongs to them. You can export the ledger. You cannot export the engine.

Switching Means Starting Over

Here's what a migration from a third-party affiliate platform actually looks like in practice:

Referral links break immediately. Every affiliate has been sharing yourplatform.com/ref/affiliate-slug style links that route through the platform's redirect infrastructure. Those links die the moment you cancel. Your affiliates are now sending traffic to dead URLs.
Attribution history is orphaned. Even if you have the CSV, your new system has no way to resolve historical conversions back to the correct affiliate unless you manually re-import and remap every record. Most platforms export commission totals, not the raw conversion events that produced them.
Affiliate trust takes a hit. You have to email every active affiliate, explain the migration, give them new links, and ask them to update everything they've published — blog posts, YouTube descriptions, newsletters. Some won't. Those referrals are permanently lost.
You rebuild the integration anyway. The Stripe webhook handler, the checkout metadata, the cookie capture logic — you write all of it fresh regardless of which new platform you move to. The only question is whether you're writing it to feed another third-party system or your own.

The Lock-In Is Structural, Not Accidental

This isn't a bug in how these platforms work. It's the business model. The harder you are to leave, the more pricing power they have over you. A platform that makes migration easy is a platform that competes on merit every renewal cycle. Most don't want that.

Self-hosted affiliate tracking software eliminates this dynamic entirely. Your data is in your database, in your schema, accessible to your queries. Your tracking logic is in your codebase. Switching tools means updating a config, not rebuilding an affiliate program.

How Affiliate Tracking Actually Works Under the Hood

Before you self-host anything, you need a clear mental model of what "affiliate tracking" actually consists of. It's three distinct components:

1. Attribution — Capturing the Referral

When a visitor arrives via an affiliate link (yourapp.com?ref=affiliate-slug), something needs to capture that ref parameter and persist it until conversion. The standard approach: read the query param, write it to a cookie with a 30–90 day expiration.

// Simplified attribution logic — runs when a visitor lands
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);
}

First-click attribution (shown above) gives credit to the first affiliate who drove the visit. The cookie isn't overwritten if it already exists. This is the most common and fair model for SaaS affiliate programs.

2. Conversion — Linking the Payment to the Referral

When the user completes a paid action, you read the cookie and attach the affiliate reference to the payment event. With Stripe, this means passing it as session metadata at checkout creation, then reading it back in the webhook.

// app/api/checkout/route.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<NextResponse> {
  // 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`,
  };

  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 });
}

Why attach to both session and subscription?
The checkout.session.completed event fires once. But if you're paying recurring commissions (e.g., 20% of every renewal), you need the ref on the subscription object so it's available on every invoice.payment_succeeded event going forward.

3. Confirmation — Webhook-Driven Commission Recording

Never trust the client-side success page for conversion confirmation. Users close tabs, skip redirects, or hit back. The Stripe webhook is the authoritative signal.

// app/api/webhooks/stripe/route.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<NextResponse> {
  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 });
}

The Database Schema You Actually Own

This is what your data looks like when it lives in your own Postgres instance — queryable, JOIN-able, fully yours:

-- Affiliates
CREATE TABLE affiliates (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug            TEXT UNIQUE NOT NULL,        -- The ?ref= value
  name            TEXT NOT NULL,
  email           TEXT UNIQUE NOT NULL,
  commission_rate NUMERIC(5,4) DEFAULT 0.20,  -- 20%
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- One-time conversions
CREATE TABLE affiliate_conversions (
  id                   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  affiliate_id         UUID NOT NULL REFERENCES affiliates(id),
  stripe_session_id    TEXT UNIQUE NOT NULL,
  stripe_customer_id   TEXT NOT NULL,
  amount_cents         INTEGER NOT NULL,
  commission_cents     INTEGER NOT NULL,
  status               TEXT NOT NULL DEFAULT 'pending', -- pending | paid | reversed
  converted_at         TIMESTAMPTZ NOT NULL,
  paid_at              TIMESTAMPTZ
);

-- 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);

When your data is in a schema you control, cross-referencing affiliate performance against churn, LTV, or plan type is a SQL query, not a support ticket.

The Build-vs-Deploy Calculation

Here's the honest breakdown of what building affiliate tracking yourself actually costs:

Component	DIY Effort	Notes
Cookie capture logic	~1 hour	Straightforward, shown above
Stripe checkout integration	~2 hours	Shown above
Stripe webhook handler	~2 hours	Shown above
Database schema + migrations	~1 hour	Shown above
Affiliate-facing portal	80–150 hours	The part you don't want to build
Payout management UI	40–80 hours	Approve, reject, mark as paid
Email notifications	20–40 hours	Commission approved, payout sent

The tracking code is 8 hours of work. The surrounding infrastructure — the portal your affiliates actually log into, the payout queue, the notification emails — is where real time disappears. That's not a reason to use a third-party platform. It's a reason to use open-source self-hosted infrastructure that ships all of it already built.

Where RefearnApp Comes In

RefearnApp is a free, open-source, self-hostable affiliate tracking platform built for exactly this stack — Next.js and Stripe — that gives you the 80–150 hours of infrastructure work without the 80–150 hours.

What it includes out of the box:

Affiliate portal — Your affiliates get a real dashboard to track their clicks, conversions, and commission history. You don't build this.
Commission engine — Configurable percentage and flat-rate commissions, with recurring attribution for subscription billing built in.
Payout tracking — Mark commissions as pending, approved, or paid. Full payout history per affiliate.
Zero revenue cut — No percentage rake on commissions. Every dollar goes to your affiliates.
Your database, your schema — When you deploy RefearnApp, the data is in your Postgres instance. You can query it, back it up, migrate it, or extend it whenever you want. No CSV exports. No support tickets. No lock-in.

The critical difference from third-party platforms: if you ever need to change tools, extend functionality, or migrate to a different payment processor, you're modifying TypeScript in a repo you own. Not starting over.

Summary

Third-party affiliate platforms don't just cost money. They cost optionality. The moment you decide to switch — and eventually you will — you discover that the real asset wasn't the dashboard or the payout UI. It was the tracking layer underneath: the referral links, the cookie logic, the attribution pipeline. All of it belongs to them.

Self-hosted affiliate tracking software means:

Your referral links are on your domain. They don't break when you change tools.
Your conversion data is in your database. You query it, you own it, you migrate it.
Your tracking logic is in your codebase. You read it, you modify it, you extend it.

- Switching costs drop to near zero. You update config, not rebuild a program.

Conclusion & Next Steps

Take Control of Your Affiliate Data

RefearnApp is fully open-source, self-hostable, and AGPL-3.0 licensed. You can deploy it completely free on your own infrastructure using Coolify or check out our direct paths:

Developer Choice: Read Deployment Docs or ⭐ Star the Repo to run it on your own VPS via Coolify with 100% data ownership.
Production Ready: Try Managed Cloud to get up and running instantly with a fully turnkey, zero-config deployment.

How to Build an Affiliate Program in Next.js (The Clean Way)

Zekariyas Berihun — Thu, 28 May 2026 14:48:56 +0000

You're shipping a Next.js SaaS. You want affiliates. You look at Rewardful — $49/month. FirstPromoter — $89/month. Impact — "contact sales." All of them to do one thing: track a ?ref= query param and attribute a Stripe payment to it.

That's it. That's the core problem. You're paying three figures a month for a cookie and a dashboard.

This guide shows you how to implement affiliate tracking yourself — the right way — and introduce a free, self-hosted alternative that handles the rest of the infrastructure you don't want to build.

The Core Logic of Affiliate Tracking in Next.js

Affiliate tracking boils down to three steps:

Capture the ?ref= query parameter when a visitor lands
Persist it in a cookie so it survives page navigation and checkout redirects
Pass it to your payment processor (Stripe) at checkout time

Capturing the Referral Param

In the App Router, you can't use useSearchParams directly in Server Components. You have two clean options:

Option A — Client Component with useSearchParams

Create a component that runs on the client and reads the URL:

// components/RefTracker.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,       // 30-day window
        sameSite: 'lax',
        secure: process.env.NODE_ENV === 'production',
      });
    }
  }, [searchParams]);

  return null; // invisible component
}

Drop this into your root layout (wrapped in <Suspense>):

// app/layout.tsx
import { Suspense } from 'react';
import { RefTracker } from '@/components/RefTracker';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Suspense fallback={null}>
          <RefTracker />
        </Suspense>
        {children}
      </body>
    </html>
  );
}

Option B — Middleware (runs on every request, zero client JS)

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  const ref = request.nextUrl.searchParams.get('ref');

  if (ref && !request.cookies.has('affiliate_ref')) {
    response.cookies.set('affiliate_ref', ref, {
      maxAge: 60 * 60 * 24 * 30, // 30 days
      httpOnly: true,
      sameSite: 'lax',
      secure: process.env.NODE_ENV === 'production',
    });
  }

  return response;
}

export const config = {
  matcher: ['/((?!_next|api|favicon.ico).*)'],
};

Middleware is the better default — it's server-side, runs before the page renders, and doesn't require client JS. Use the Client Component approach only if you need the ref value accessible in browser JS.

Why a Cookie, Not localStorage?

Cookies are readable server-side — your API routes can access them during checkout
localStorage is origin-scoped but not path-scoped — fine for SPAs, fragile in server-rendered flows
Cookies survive full-page reloads and redirects — Stripe checkout is a full redirect

Step-by-Step Code Implementation

Step 1 — Full Ref Capture + Cookie (TypeScript)

Here's a production-ready version using the middleware approach with validation:

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const REF_COOKIE = 'affiliate_ref';
const REF_MAX_AGE = 60 * 60 * 24 * 30; // 30 days

function isValidRef(ref: string): boolean {
  // Alphanumeric + hyphens only, 3–32 chars
  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;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api/).*)'],
};

Step 2 — Pass the Ref to Stripe Checkout

In your checkout API route, read the cookie and attach it to the Stripe session as metadata:

// app/api/checkout/route.ts
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`,
    // Affiliate attribution lives here
    metadata: {
      affiliate_ref: affiliateRef ?? '',
    },
    subscription_data: affiliateRef
      ? {
          metadata: {
            affiliate_ref: affiliateRef,
          },
        }
      : undefined,
  });

  return NextResponse.json({ url: session.url });
}

Key points:

metadata on the session is readable in your Stripe webhook
subscription_data.metadata ensures the ref persists on the subscription object for recurring commission tracking
A missing ref gets an empty string — never undefined, which would cause a Stripe API error

Step 3 — Read the Ref in Your Stripe Webhook

// app/api/webhooks/stripe/route.ts (abbreviated)
import Stripe from 'stripe';

export async function POST(request: Request) {
  const event = stripe.webhooks.constructEvent(/* ... */);

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session;
    const affiliateRef = session.metadata?.affiliate_ref;

    if (affiliateRef) {
      // Credit the affiliate — look up by ref slug, record the conversion
      await creditAffiliate(affiliateRef, session.amount_total ?? 0);
    }
  }
}

The Infrastructure Problem: Self-Hosting vs. SaaS

Tracking the cookie is 50 lines of code. What you actually get from Rewardful for $49/month is everything else:

Affiliate dashboard — a portal where affiliates check their clicks, conversions, and earnings
Payout management — calculating commissions, generating invoices, sending payments
Multi-tier commissions — percentage vs. flat rate, recurring vs. one-time
Link management — custom slugs, campaign-level tracking

Building all of that from scratch is weeks of work. You don't want to do it. You want to ship your actual product.

Enter RefearnApp

RefearnApp is a free, open-source, self-hosted affiliate tracking platform built specifically for Next.js + Stripe workflows.

What it gives you out of the box:

Affiliate dashboard — your affiliates get a real portal with their stats
Stripe-native integration — webhooks, metadata attribution, and payout tracking built in
Commission engine — configurable percentage or flat-rate commissions, recurring support
Zero monthly cost — deploy it on your own infra, keep 100% of your revenue
No vendor lock-in — it's your database, your data, your affiliate relationships

It's the plug-and-play backend layer that sits between your cookie tracking code (above) and your affiliates. Instead of building creditAffiliate() yourself and wiring up a dashboard, you point your webhook at RefearnApp and it handles attribution, aggregation, and reporting.

Stack it's built for: Next.js (App Router), Stripe, PostgreSQL — the same stack you're already using.

Conclusion & Next Steps

Take Control of Your Affiliate Data

RefearnApp is fully open-source, self-hostable, and AGPL-3.0 licensed. You can deploy it completely free on your own infrastructure using Coolify or check out our direct paths:

Developer Choice: Read Deployment Docs or ⭐ Star the Repo to run it on your own VPS via Coolify with 100% data ownership.
Production Ready: Try Managed Cloud to get up and running instantly with a fully turnkey, zero-config deployment.

How to Build an Affiliate Program in Next.js (The Clean Way)

Zekariyas Berihun — Thu, 28 May 2026 14:39:41 +0000

That's it. That's the core problem. You're paying three figures a month for a cookie and a dashboard.

The Core Logic of Affiliate Tracking in Next.js

Affiliate tracking boils down to three steps:

Capture the ?ref= query parameter when a visitor lands
Persist it in a cookie so it survives page navigation and checkout redirects
Pass it to your payment processor (Stripe) at checkout time ### Capturing the Referral Param

In the App Router, you can't use useSearchParams directly in Server Components. You have two clean options:

Option A — Client Component with useSearchParams

Create a component that runs on the client and reads the URL:

// components/RefTracker.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,       // 30-day window
        sameSite: 'lax',
        secure: process.env.NODE_ENV === 'production',
      });
    }
  }, [searchParams]);

  return null; // invisible component
}

Drop this into your root layout (wrapped in <Suspense>):

// app/layout.tsx
import { Suspense } from 'react';
import { RefTracker } from '@/components/RefTracker';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Suspense fallback={null}>
          <RefTracker />
        </Suspense>
        {children}
      </body>
    </html>
  );
}

Option B — Middleware (runs on every request, zero client JS)

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  const ref = request.nextUrl.searchParams.get('ref');

  if (ref && !request.cookies.has('affiliate_ref')) {
    response.cookies.set('affiliate_ref', ref, {
      maxAge: 60 * 60 * 24 * 30, // 30 days
      httpOnly: true,
      sameSite: 'lax',
      secure: process.env.NODE_ENV === 'production',
    });
  }

  return response;
}

export const config = {
  matcher: ['/((?!_next|api|favicon.ico).*)'],
};

Why a Cookie, Not localStorage?

Cookies are readable server-side — your API routes can access them during checkout
localStorage is origin-scoped but not path-scoped — fine for SPAs, fragile in server-rendered flows

- Cookies survive full-page reloads and redirects — Stripe checkout is a full redirect

Step-by-Step Code Implementation

Step 1 — Full Ref Capture + Cookie (TypeScript)

Here's a production-ready version using the middleware approach with validation:

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const REF_COOKIE = 'affiliate_ref';
const REF_MAX_AGE = 60 * 60 * 24 * 30; // 30 days

function isValidRef(ref: string): boolean {
  // Alphanumeric + hyphens only, 3–32 chars
  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;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api/).*)'],
};

Step 2 — Pass the Ref to Stripe Checkout

In your checkout API route, read the cookie and attach it to the Stripe session as metadata:

// app/api/checkout/route.ts
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`,
    // Affiliate attribution lives here
    metadata: {
      affiliate_ref: affiliateRef ?? '',
    },
    subscription_data: affiliateRef
      ? {
          metadata: {
            affiliate_ref: affiliateRef,
          },
        }
      : undefined,
  });

  return NextResponse.json({ url: session.url });
}

Key points:

metadata on the session is readable in your Stripe webhook
subscription_data.metadata ensures the ref persists on the subscription object for recurring commission tracking
A missing ref gets an empty string — never undefined, which would cause a Stripe API error ### Step 3 — Read the Ref in Your Stripe Webhook

// app/api/webhooks/stripe/route.ts (abbreviated)
import Stripe from 'stripe';

export async function POST(request: Request) {
  const event = stripe.webhooks.constructEvent(/* ... */);

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session;
    const affiliateRef = session.metadata?.affiliate_ref;

    if (affiliateRef) {
      // Credit the affiliate — look up by ref slug, record the conversion
      await creditAffiliate(affiliateRef, session.amount_total ?? 0);
    }
  }
}

The Infrastructure Problem: Self-Hosting vs. SaaS

Tracking the cookie is 50 lines of code. What you actually get from Rewardful for $49/month is everything else:

Affiliate dashboard — a portal where affiliates check their clicks, conversions, and earnings
Payout management — calculating commissions, generating invoices, sending payments
Multi-tier commissions — percentage vs. flat rate, recurring vs. one-time
Link management — custom slugs, campaign-level tracking Building all of that from scratch is weeks of work. You don't want to do it. You want to ship your actual product.

Enter RefearnApp

RefearnApp is a free, open-source, self-hosted affiliate tracking platform built specifically for Next.js + Stripe workflows.

What it gives you out of the box:

Affiliate dashboard — your affiliates get a real portal with their stats
Stripe-native integration — webhooks, metadata attribution, and payout tracking built in
Commission engine — configurable percentage or flat-rate commissions, recurring support
Zero monthly cost — deploy it on your own infra, keep 100% of your revenue
No vendor lock-in — it's your database, your data, your affiliate relationships It's the plug-and-play backend layer that sits between your cookie tracking code (above) and your affiliates. Instead of building creditAffiliate() yourself and wiring up a dashboard, you point your webhook at RefearnApp and it handles attribution, aggregation, and reporting.

Stack it's built for: Next.js (App Router), Stripe, PostgreSQL — the same stack you're already using.

Conclusion & Next Steps

Take Control of Your Affiliate Data

RefearnApp is fully open-source, self-hostable, and AGPL-3.0 licensed. You can deploy it completely free on your own infrastructure using Coolify or check out our direct paths:

Developer Choice: Read Deployment Docs or ⭐ Star the Repo to run it on your own VPS via Coolify with 100% data ownership.
Production Ready: Try Managed Cloud to get up and running instantly with a fully turnkey, zero-config deployment.