django-referral-system

A plug-and-play Django referral engine. Track promoters, reward commissions, manage payouts — all wired up in minutes.

Full documentation: Read the Docs

What it does

Area	Capability
Promoters	Create and manage promoters with unique referral tokens and links
Referral tracking	Track sign-ups, activation status, and click counts per link
Commissions	Configurable commission rates tied to the active referral program
Payouts	Wise CSV export; auto-skip promoters below minimum withdrawal balance
Refunds	Commission is automatically reversed when a referred user refunds
Email invitations	Send branded HTML invite emails via a custom template

Only one referral program can be active at a time, keeping the logic focused and predictable.

1. Install

pip install django-referral-system

Requires Python 3.9 – 3.14 and Django 4.2+.

2. Add to INSTALLED_APPS

INSTALLED_APPS = [
    ...
    "referrals",
]

3. Mount the URLs

from django.urls import path, include

urlpatterns = [
    ...
    path("referrals/", include("referrals.urls")),
]

4. Migrate

python manage.py migrate

5. Create a referral program

python manage.py create_referral_program \
    --name="My Referral Program" \
    --commission-rate=5.00 \
    --min-withdrawal-balance=10.00

Setting a program as active automatically deactivates any existing active program.

Variable	Purpose
`BASE_REFERRAL_LINK`	Base URL used when generating referral links
`BASE_EMAIL`	Sender address for invitation emails

MIT — see LICENSE for details.

Issues and pull requests are welcome. If this project saves you time, a star on GitHub goes a long way. github star

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution for django-referral-system 0.3.2
File	Size	Uploaded
django_referral_system-0.3.2.tar.gz	24.5 kB	Apr 21, 2026	Details

Table of built distributions (wheels) for django-referral-system 0.3.2
File	Interpreter	ABI	Platform	Reset
django_referral_system-0.3.2-py3-none-any.whl 31.3 kB Apr 21, 2026	Python 3	none	any	Details

Total release size: 55.8 kB

Download URL	django_referral_system-0.3.2.tar.gz
Size	24.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`e2799f7cfa03c95510a79493e6cfe91d1a2011cfb480baf98475594bb62cc111`
BLAKE2b-256 checksum How to use checksums	`46c475307129e3bb34666f4a24f740d75ecc1147c5cc598f13b6a4ca8ad5c859`
Upload date	Apr 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.17`

Download URL	django_referral_system-0.3.2-py3-none-any.whl
Size	31.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7d8819287d0e0114821c3fa99201851461b70277ce9bbea6f83d36fa9f32346b`
BLAKE2b-256 checksum How to use checksums	`1aeec5492e0f3ae6c3373b973e28590bf1950a2053d27274af5299171a803783`
Upload date	Apr 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.8.17`