Documentation

Name: Refferq
Availability: InStock
Rating: 4.9 (127 reviews)
Author: Refferq

Welcome to the Refferq documentation. Refferq is an open-source affiliate marketing platform engineered with Next.js 15, TypeScript, PostgreSQL, and Prisma. This comprehensive guide walks you through installation, configuration, core features, API integration, and deployment.

Refferq v1.1.0 introduces real-time analytics dashboards, a full webhook event system, and the Reports API.

Quick Start

Get Refferq up and running in under 5 minutes:

bash

# 1. Clone the repository
git clone https://github.com/Refferq/Refferq.git
cd Refferq

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your database URL and secrets

# 4. Set up the database
npm run db:generate
npm run db:push

# 5. Start the dev server
npm run dev

Your Refferq instance will be running at http://localhost:3000

Installation

System Requirements

Node.js 18+ (LTS recommended)
PostgreSQL 12+
npm or yarn

Docker PostgreSQL

bash

docker run --name refferq-db \
  -e POSTGRES_USER=refferq \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=refferq \
  -p 5432:5432 -d postgres:15

Configuration

Required Environment Variables

env

DATABASE_URL=postgresql://user:password@localhost:5432/refferq
JWT_SECRET=your-secret-min-32-characters-long
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com
NEXT_PUBLIC_APP_URL=https://yourdomain.com

Optional Variables

env

ADMIN_EMAILS=admin@yourdomain.com
NODE_ENV=production

Affiliate Management

Affiliates go through a registration flow with OTP verification:

Affiliate submits registration form
OTP sent to their email for verification
Account created with PENDING status
Admin reviews and approves
Affiliate receives approval email with referral code

Affiliate statuses: PENDING, ACTIVE, SUSPENDED, REJECTED

Tracking Setup

JavaScript Tracker

Add the tracking script to your website:

html

<!-- Add before closing </body> tag -->
<script src="https://yourdomain.com/scripts/refferq-tracker.js"
        data-site="your-site-id">
</script>

Server-Side Tracking

javascript

// Record a conversion via API
const response = await fetch('/api/track/conversion', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    referralCode: 'JOHN-A1B2',
    amountCents: 9900, // $99.00
    metadata: { orderId: 'ORD-123' }
  })
});

Commissions

Commission rates are configured at the partner group level. Each affiliate automatically inherits the commission rate of their assigned group:

typescript

// Commission calculation
const rate = affiliate.partnerGroup?.commissionRate || defaultRate;
const commissionCents = Math.round(amountCents * (rate / 100));

// All monetary values stored as cents (integers)
// Display: (amountCents / 100).toFixed(2)

Payouts

Manage affiliate payouts through the admin panel:

Affiliate accrues commission balance from conversions
Affiliate requests payout (or admin initiates)
Admin reviews and approves the payout request
Admin processes payment via preferred method
Payout marked as completed, balance updated

Authentication

Refferq uses JWT tokens stored in HTTP-only cookies:

bash

# Login
POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "your-password"
}

# Response sets auth-token cookie automatically

API Endpoints

Authentication

POST/api/auth/loginLogin

POST/api/auth/registerRegister

POST/api/auth/logoutLogout

GET/api/auth/meGet current user

Admin

GET/api/admin/affiliatesList affiliates

GET/api/admin/referralsList referrals

GET/api/admin/transactionsList transactions

GET/api/admin/payoutsList payouts

GET/api/admin/partner-groupsPartner groups

GET/api/admin/settingsSettings

Affiliate

GET/api/affiliate/dashboardDashboard data

GET/api/affiliate/referralsMy referrals

GET/api/affiliate/commissionsMy commissions

POST/api/affiliate/payoutRequest payout

Tracking

POST/api/track/clickTrack click

POST/api/track/conversionTrack conversion

Webhooks

New in v1.1.0

Refferq supports 12 webhook event types for real-time system integration:

affiliate.created

affiliate.approved

affiliate.suspended

referral.created

referral.converted

referral.expired

commission.created

commission.approved

commission.paid

payout.requested

payout.approved

payout.completed

All webhooks are signed with HMAC-SHA256 for security. Failed deliveries are retried with exponential backoff.

Reports API

New in v1.1.0

bash

GET /api/admin/reports/analytics?startDate=2025-01-01&endDate=2025-12-31

# Response
{
  "totalClicks": 15420,
  "totalConversions": 892,
  "conversionRate": 5.78,
  "totalRevenueCents": 8920000,
  "totalCommissionCents": 892000,
  "topAffiliates": [...]
}

Deploy to Vercel

Push your code to GitHub
Import the repository in Vercel
Set all environment variables
Deploy — Vercel handles the rest

Vercel's free tier is sufficient for most small to medium affiliate programs.

Docker Deployment

yaml

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://refferq:password@db:5432/refferq
      - JWT_SECRET=your-secret-here
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=refferq
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=refferq
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

VPS / Cloud Deployment

bash

# Install PM2
npm install -g pm2

# Build the application
npm run build

# Start with PM2
pm2 start npm --name "refferq" -- start

# Enable startup script
pm2 startup
pm2 save

Need Help?

Our community and documentation are here to support you at every step.

Community Discussions Report a Bug

Documentation

Refferq v1.1.0 introduces real-time analytics dashboards, a full webhook event system, and the Reports API.

Quick Start

Get Refferq up and running in under 5 minutes:

bash

# 1. Clone the repository
git clone https://github.com/Refferq/Refferq.git
cd Refferq

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your database URL and secrets

# 4. Set up the database
npm run db:generate
npm run db:push

# 5. Start the dev server
npm run dev

Your Refferq instance will be running at http://localhost:3000

Installation

System Requirements

Node.js 18+ (LTS recommended)
PostgreSQL 12+
npm or yarn

Docker PostgreSQL

bash

docker run --name refferq-db \
  -e POSTGRES_USER=refferq \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=refferq \
  -p 5432:5432 -d postgres:15

Configuration

Required Environment Variables

env

DATABASE_URL=postgresql://user:password@localhost:5432/refferq
JWT_SECRET=your-secret-min-32-characters-long
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com
NEXT_PUBLIC_APP_URL=https://yourdomain.com

Optional Variables

env

ADMIN_EMAILS=admin@yourdomain.com
NODE_ENV=production

Affiliate Management

Affiliates go through a registration flow with OTP verification:

Affiliate submits registration form
OTP sent to their email for verification
Account created with PENDING status
Admin reviews and approves
Affiliate receives approval email with referral code

Affiliate statuses: PENDING, ACTIVE, SUSPENDED, REJECTED

Tracking Setup

JavaScript Tracker

Add the tracking script to your website:

html

<!-- Add before closing </body> tag -->
<script src="https://yourdomain.com/scripts/refferq-tracker.js"
        data-site="your-site-id">
</script>

Server-Side Tracking

javascript

// Record a conversion via API
const response = await fetch('/api/track/conversion', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    referralCode: 'JOHN-A1B2',
    amountCents: 9900, // $99.00
    metadata: { orderId: 'ORD-123' }
  })
});

Commissions

Commission rates are configured at the partner group level. Each affiliate automatically inherits the commission rate of their assigned group:

typescript

// Commission calculation
const rate = affiliate.partnerGroup?.commissionRate || defaultRate;
const commissionCents = Math.round(amountCents * (rate / 100));

// All monetary values stored as cents (integers)
// Display: (amountCents / 100).toFixed(2)

Payouts

Manage affiliate payouts through the admin panel:

Affiliate accrues commission balance from conversions
Affiliate requests payout (or admin initiates)
Admin reviews and approves the payout request
Admin processes payment via preferred method
Payout marked as completed, balance updated

Authentication

Refferq uses JWT tokens stored in HTTP-only cookies:

bash

# Login
POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "your-password"
}

# Response sets auth-token cookie automatically

API Endpoints

Authentication

POST/api/auth/loginLogin

POST/api/auth/registerRegister

POST/api/auth/logoutLogout

GET/api/auth/meGet current user

Admin

GET/api/admin/affiliatesList affiliates

GET/api/admin/referralsList referrals

GET/api/admin/transactionsList transactions

GET/api/admin/payoutsList payouts

GET/api/admin/partner-groupsPartner groups

GET/api/admin/settingsSettings

Affiliate

GET/api/affiliate/dashboardDashboard data

GET/api/affiliate/referralsMy referrals

GET/api/affiliate/commissionsMy commissions

POST/api/affiliate/payoutRequest payout

Tracking

POST/api/track/clickTrack click

POST/api/track/conversionTrack conversion

Webhooks

New in v1.1.0

Refferq supports 12 webhook event types for real-time system integration:

affiliate.created

affiliate.approved

affiliate.suspended

referral.created

referral.converted

referral.expired

commission.created

commission.approved

commission.paid

payout.requested

payout.approved

payout.completed

All webhooks are signed with HMAC-SHA256 for security. Failed deliveries are retried with exponential backoff.

Reports API

New in v1.1.0

bash

GET /api/admin/reports/analytics?startDate=2025-01-01&endDate=2025-12-31

# Response
{
  "totalClicks": 15420,
  "totalConversions": 892,
  "conversionRate": 5.78,
  "totalRevenueCents": 8920000,
  "totalCommissionCents": 892000,
  "topAffiliates": [...]
}

Deploy to Vercel

Push your code to GitHub
Import the repository in Vercel
Set all environment variables
Deploy — Vercel handles the rest

Vercel's free tier is sufficient for most small to medium affiliate programs.

Docker Deployment

yaml

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://refferq:password@db:5432/refferq
      - JWT_SECRET=your-secret-here
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=refferq
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=refferq
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

VPS / Cloud Deployment

bash

# Install PM2
npm install -g pm2

# Build the application
npm run build

# Start with PM2
pm2 start npm --name "refferq" -- start

# Enable startup script
pm2 startup
pm2 save

Need Help?

Our community and documentation are here to support you at every step.

Community Discussions Report a Bug