Metadata-Version: 2.1
Name: django-referral-system
Version: 0.3.2
Summary: A Django app for managing referral programs, promoters, referrals, and tracking referral performance with advanced features like commission setting, invitation management, and Wise payouts.
Author-email: Soldatov Serhii <soldatov.own@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/soldatov-ss/django-referral-system
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: <3.15,>=3.9
Description-Content-Type: text/markdown
Requires-Dist: djangorestframework <3.17,>=3.16
Requires-Dist: python-dotenv <1.1,>=1.0
Requires-Dist: Django <5.0,>=4.2 ; python_version < "3.10"
Requires-Dist: pandas <2.2,>=2.0 ; python_version < "3.12"
Requires-Dist: numpy <2.0,>=1.26 ; python_version < "3.13"
Requires-Dist: pydantic <2.11,>=2.0 ; python_version < "3.14"
Requires-Dist: Django <5.3,>=4.2 ; python_version >= "3.10" and python_version < "3.13"
Requires-Dist: pandas <3.0,>=2.2.3 ; python_version >= "3.12"
Requires-Dist: Django <5.3,>=5.1.3 ; python_version >= "3.13"
Requires-Dist: numpy <2.3,>=2.1 ; python_version >= "3.13"
Requires-Dist: pydantic <3.0,>=2.11 ; python_version >= "3.14"
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-django ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: coverage ; extra == 'test'
Requires-Dist: ruff ; extra == 'test'
Requires-Dist: ipython ; extra == 'test'

# django-referral-system

[![CI](https://github.com/soldatov-ss/django-referral-system/actions/workflows/ci.yml/badge.svg)](https://github.com/soldatov-ss/django-referral-system/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/django-referral-system.svg)](https://badge.fury.io/py/django-referral-system)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/soldatov-ss/django-referral-system/blob/main/LICENSE)
[![Python Versions](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue.svg)](https://pypi.org/project/django-referral-system/)
[![Coverage Status](https://coveralls.io/repos/github/soldatov-ss/django-referral-system/badge.svg?branch=main)](https://coveralls.io/github/soldatov-ss/django-referral-system?branch=main)

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

Full documentation: [Read the Docs](https://django-referral-system.readthedocs.io/en/latest/index.html)

---

## 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.

---

## Quick start

**1. Install**

```bash
pip install django-referral-system
```

Requires Python 3.9 – 3.14 and Django 4.2+.

**2. Add to `INSTALLED_APPS`**

```python
INSTALLED_APPS = [
    ...
    "referrals",
]
```

**3. Mount the URLs**

```python
from django.urls import path, include

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

**4. Migrate**

```bash
python manage.py migrate
```

**5. Create a referral program**

```bash
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.

---

## Environment variables

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

---

## License

MIT — see [LICENSE](LICENSE) for details.

## Contributing

Issues and pull requests are welcome. If this project saves you time, a star on GitHub goes a long way. ![github star](docs/github-star.png)
