# Django Affiliate System
[](https://badge.fury.io/py/django-affiliate-system)
[](https://pypi.org/project/django-affiliate-system/)
[](https://pypi.org/project/django-affiliate-system/)
[](https://opensource.org/licenses/MIT)
A comprehensive, production-ready Django affiliate marketing and referral tracking system with built-in REST API support.
## Features
- 🎯 **Multi-tenant Support** - Manage multiple affiliate programs
- 🔗 **Referral Link Management** - Generate and track custom referral links
- 📊 **Advanced Analytics** - Track clicks, conversions, and commissions
- 💰 **Commission Calculation** - Flexible commission rules and payouts
- 🔐 **Hybrid Authentication** - JWT and API key authentication
- 📱 **Session Tracking** - Multi-touch attribution models
- 🎨 **RESTful API** - Complete REST API with Django REST Framework
- 🔔 **Webhook Support** - External conversion tracking
- ⚡ **Celery Task Support** (Optional)
## Requirements
- Python 3.9+
- Django 4.0+
- Django REST Framework 3.14+
## Installation
### Basic Installation
```bash
pip install django-affiliate-system
```
### With Optional Dependencies
```bash
# With Celery support
pip install django-affiliate-system[celery]
# With all optional features
pip install django-affiliate-system[all]
```
## Quick Start
### 1. Add to Installed Apps
Add `django_affiliate_system` and its dependencies to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
# ...
'rest_framework',
'rest_framework_simplejwt',
'django_affiliate_system',
]
```
### 2. Add Middleware
```python
MIDDLEWARE = [
# ...
'django_affiliate_system.middleware.CORSMiddleware',
'django_affiliate_system.middleware.TenantMiddleware',
]
```
### 3. Configure Settings
```python
# Django REST Framework
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': [
'django_affiliate_system.authentication.HybridAuthentication',
],
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAuthenticated',
],
}
# Django Affiliate System
AFFILIATE_SYSTEM = {
'DOMAIN_PROTOCOL': 'https',
'DOMAIN': 'yourdomain.com',
'DEFAULT_COMMISSION_RATE': 10.0, # 10%
'COOKIE_DURATION_DAYS': 30,
'ALLOWED_CORS_ORIGINS': [
'http://localhost:3000',
'https://yourdomain.com',
],
}
```
### 4. Include URLs
```python
from django.urls import path, include
urlpatterns = [
# ...
path('affiliate/', include('django_affiliate_system.urls')),
]
```
### 5. Run Migrations
```bash
python manage.py migrate django_affiliate_system
```
### 6. Create a Tenant
```python
from django_affiliate_system.models import Tenant
from django.contrib.auth import get_user_model
User = get_user_model()
owner = User.objects.create_user('owner@example.com', password='password')
tenant = Tenant.objects.create(
name="My Affiliate Program",
slug="my-program",
destination_url="https://mysite.com",
owner=owner,
default_commission_rate=15.0
)
print(f"API Key: {tenant.api_key}")
```
## API Usage
### Authentication
The system supports two authentication methods:
#### 1. JWT Authentication (for user-facing APIs)
```bash
# Get token
curl -X POST http://localhost:8000/affiliate/api/auth/token/ \
-H "Content-Type: application/json" \
-d '{"username": "user@example.com", "password": "password"}'
# Use token
curl http://localhost:8000/affiliate/api/affiliates/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
#### 2. API Key Authentication (for tenant APIs)
```bash
curl http://localhost:8000/affiliate/api/tenants/ \
-H "X-API-Key: YOUR_TENANT_API_KEY"
```
### Create an Affiliate
```bash
curl -X POST http://localhost:8000/affiliate/api/affiliates/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-API-Key: YOUR_TENANT_API_KEY" \
-H "Content-Type: application/json"
```
### Create a Referral Link
```bash
curl -X POST http://localhost:8000/affiliate/api/referral-links/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-API-Key: YOUR_TENANT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"slug": "my-custom-link",
"destination_url": "https://mysite.com/product"
}'
```
### Track Events
```bash
# Track a click
curl -X POST http://localhost:8000/affiliate/api/track/ \
-H "Content-Type: application/json" \
-d '{
"event_type": "click",
"referral_code": "AFFILIATE_CODE",
"session_id": "unique-session-id"
}'
# Track a conversion
curl -X POST http://localhost:8000/affiliate/api/track/ \
-H "Content-Type: application/json" \
-d '{
"event_type": "purchase",
"referral_code": "AFFILIATE_CODE",
"session_id": "unique-session-id",
"conversion_value": 99.99,
"is_conversion": true
}'
```
### Get Affiliate Statistics
```bash
curl http://localhost:8000/affiliate/api/affiliates/stats/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-API-Key: YOUR_TENANT_API_KEY"
```
## Models Overview
- **Tenant** - Platforms using the affiliate system
- **Affiliate** - Users who refer others
- **ReferralLink** - Unique referral links for affiliates
- **ReferralAction** - Track all referral actions (clicks, signups, purchases)
- **Commission** - Commissions earned from referrals
- **Payout** - Payments to affiliates
- **CommissionRule** - Rules for calculating commissions
- **ReferralSession** - Track user sessions across touchpoints
## Advanced Features
### Multi-Touch Attribution
```python
from django_affiliate_system.services.tracking import process_tracking_event
action = process_tracking_event(
data={
'event_type': 'purchase',
'referral_code': 'REF123',
'session_id': 'session-uuid',
'conversion_value': 100.00,
'is_conversion': True
},
meta=request.META,
use_sessions=True,
attribution_model='first_click' # or 'last_click'
)
```
### Custom Commission Rules
```python
from django_affiliate_system.models import CommissionRule
rule = CommissionRule.objects.create(
tenant=tenant,
name="Premium Product Commission",
action_type="purchase",
is_percentage=True,
value=20.0, # 20%
min_value=10.00,
max_value=100.00,
is_active=True
)
```
### Celery Tasks (Optional)
```python
# tasks.py in your project
from django_affiliate_system.tasks import process_payout
# Trigger payout processing
process_payout.delay(payout_id=123)
```
## Testing
```bash
# Install dev dependencies
pip install django-affiliate-system[dev]
# Run tests
pytest
# With coverage
pytest --cov=django_affiliate_system
```
## Documentation
Full documentation is available at [https://django-affiliate-system.readthedocs.io/](https://django-affiliate-system.readthedocs.io/)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📧 Email: aayodeji.f@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/aayodejii/django-affiliate-system/issues)
- 📖 Documentation: [Read the Docs](https://django-affiliate-system.readthedocs.io/)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
## Credits
Created and maintained by [Ayodeji Akenroye](https://github.com/aayodejii).
# django-affiliate-system
Raw data
{
"_id": null,
"home_page": null,
"name": "django-affiliate-system",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "django, affiliate, referral, tracking, commission, marketing",
"author": null,
"author_email": "Ayodeji Akenroye <aayodeji.f@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1e/ac/07eb579f2ec22a2dd30ea548ed0ded2cb84f5f14fbe9e4b8d73c62a8d541/django_affiliate_system-0.1.0a3.tar.gz",
"platform": null,
"description": "# Django Affiliate System\n\n[](https://badge.fury.io/py/django-affiliate-system)\n[](https://pypi.org/project/django-affiliate-system/)\n[](https://pypi.org/project/django-affiliate-system/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive, production-ready Django affiliate marketing and referral tracking system with built-in REST API support.\n\n## Features\n\n- \ud83c\udfaf **Multi-tenant Support** - Manage multiple affiliate programs\n- \ud83d\udd17 **Referral Link Management** - Generate and track custom referral links\n- \ud83d\udcca **Advanced Analytics** - Track clicks, conversions, and commissions\n- \ud83d\udcb0 **Commission Calculation** - Flexible commission rules and payouts\n- \ud83d\udd10 **Hybrid Authentication** - JWT and API key authentication\n- \ud83d\udcf1 **Session Tracking** - Multi-touch attribution models\n- \ud83c\udfa8 **RESTful API** - Complete REST API with Django REST Framework\n- \ud83d\udd14 **Webhook Support** - External conversion tracking\n- \u26a1 **Celery Task Support** (Optional)\n\n## Requirements\n\n- Python 3.9+\n- Django 4.0+\n- Django REST Framework 3.14+\n\n## Installation\n\n### Basic Installation\n\n```bash\npip install django-affiliate-system\n```\n\n### With Optional Dependencies\n\n```bash\n\n# With Celery support\npip install django-affiliate-system[celery]\n\n# With all optional features\npip install django-affiliate-system[all]\n```\n\n## Quick Start\n\n### 1. Add to Installed Apps\n\nAdd `django_affiliate_system` and its dependencies to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n # ...\n 'rest_framework',\n 'rest_framework_simplejwt',\n 'django_affiliate_system',\n]\n```\n\n### 2. Add Middleware\n\n```python\nMIDDLEWARE = [\n # ...\n 'django_affiliate_system.middleware.CORSMiddleware',\n 'django_affiliate_system.middleware.TenantMiddleware',\n]\n```\n\n### 3. Configure Settings\n\n```python\n# Django REST Framework\nREST_FRAMEWORK = {\n 'DEFAULT_AUTHENTICATION_CLASSES': [\n 'django_affiliate_system.authentication.HybridAuthentication',\n ],\n 'DEFAULT_PERMISSION_CLASSES': [\n 'rest_framework.permissions.IsAuthenticated',\n ],\n}\n\n# Django Affiliate System\nAFFILIATE_SYSTEM = {\n 'DOMAIN_PROTOCOL': 'https',\n 'DOMAIN': 'yourdomain.com',\n 'DEFAULT_COMMISSION_RATE': 10.0, # 10%\n 'COOKIE_DURATION_DAYS': 30,\n 'ALLOWED_CORS_ORIGINS': [\n 'http://localhost:3000',\n 'https://yourdomain.com',\n ],\n}\n```\n\n### 4. Include URLs\n\n```python\nfrom django.urls import path, include\n\nurlpatterns = [\n # ...\n path('affiliate/', include('django_affiliate_system.urls')),\n]\n```\n\n### 5. Run Migrations\n\n```bash\npython manage.py migrate django_affiliate_system\n```\n\n### 6. Create a Tenant\n\n```python\nfrom django_affiliate_system.models import Tenant\nfrom django.contrib.auth import get_user_model\n\nUser = get_user_model()\nowner = User.objects.create_user('owner@example.com', password='password')\n\ntenant = Tenant.objects.create(\n name=\"My Affiliate Program\",\n slug=\"my-program\",\n destination_url=\"https://mysite.com\",\n owner=owner,\n default_commission_rate=15.0\n)\n\nprint(f\"API Key: {tenant.api_key}\")\n```\n\n## API Usage\n\n### Authentication\n\nThe system supports two authentication methods:\n\n#### 1. JWT Authentication (for user-facing APIs)\n\n```bash\n# Get token\ncurl -X POST http://localhost:8000/affiliate/api/auth/token/ \\\n -H \"Content-Type: application/json\" \\\n -d '{\"username\": \"user@example.com\", \"password\": \"password\"}'\n\n# Use token\ncurl http://localhost:8000/affiliate/api/affiliates/ \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n#### 2. API Key Authentication (for tenant APIs)\n\n```bash\ncurl http://localhost:8000/affiliate/api/tenants/ \\\n -H \"X-API-Key: YOUR_TENANT_API_KEY\"\n```\n\n### Create an Affiliate\n\n```bash\ncurl -X POST http://localhost:8000/affiliate/api/affiliates/ \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"X-API-Key: YOUR_TENANT_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n### Create a Referral Link\n\n```bash\ncurl -X POST http://localhost:8000/affiliate/api/referral-links/ \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"X-API-Key: YOUR_TENANT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"slug\": \"my-custom-link\",\n \"destination_url\": \"https://mysite.com/product\"\n }'\n```\n\n### Track Events\n\n```bash\n# Track a click\ncurl -X POST http://localhost:8000/affiliate/api/track/ \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"event_type\": \"click\",\n \"referral_code\": \"AFFILIATE_CODE\",\n \"session_id\": \"unique-session-id\"\n }'\n\n# Track a conversion\ncurl -X POST http://localhost:8000/affiliate/api/track/ \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"event_type\": \"purchase\",\n \"referral_code\": \"AFFILIATE_CODE\",\n \"session_id\": \"unique-session-id\",\n \"conversion_value\": 99.99,\n \"is_conversion\": true\n }'\n```\n\n### Get Affiliate Statistics\n\n```bash\ncurl http://localhost:8000/affiliate/api/affiliates/stats/ \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"X-API-Key: YOUR_TENANT_API_KEY\"\n```\n\n## Models Overview\n\n- **Tenant** - Platforms using the affiliate system\n- **Affiliate** - Users who refer others\n- **ReferralLink** - Unique referral links for affiliates\n- **ReferralAction** - Track all referral actions (clicks, signups, purchases)\n- **Commission** - Commissions earned from referrals\n- **Payout** - Payments to affiliates\n- **CommissionRule** - Rules for calculating commissions\n- **ReferralSession** - Track user sessions across touchpoints\n\n## Advanced Features\n\n### Multi-Touch Attribution\n\n```python\nfrom django_affiliate_system.services.tracking import process_tracking_event\n\naction = process_tracking_event(\n data={\n 'event_type': 'purchase',\n 'referral_code': 'REF123',\n 'session_id': 'session-uuid',\n 'conversion_value': 100.00,\n 'is_conversion': True\n },\n meta=request.META,\n use_sessions=True,\n attribution_model='first_click' # or 'last_click'\n)\n```\n\n### Custom Commission Rules\n\n```python\nfrom django_affiliate_system.models import CommissionRule\n\nrule = CommissionRule.objects.create(\n tenant=tenant,\n name=\"Premium Product Commission\",\n action_type=\"purchase\",\n is_percentage=True,\n value=20.0, # 20%\n min_value=10.00,\n max_value=100.00,\n is_active=True\n)\n```\n\n### Celery Tasks (Optional)\n\n```python\n# tasks.py in your project\nfrom django_affiliate_system.tasks import process_payout\n\n# Trigger payout processing\nprocess_payout.delay(payout_id=123)\n```\n\n## Testing\n\n```bash\n# Install dev dependencies\npip install django-affiliate-system[dev]\n\n# Run tests\npytest\n\n# With coverage\npytest --cov=django_affiliate_system\n```\n\n## Documentation\n\nFull documentation is available at [https://django-affiliate-system.readthedocs.io/](https://django-affiliate-system.readthedocs.io/)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: aayodeji.f@gmail.com\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/aayodejii/django-affiliate-system/issues)\n- \ud83d\udcd6 Documentation: [Read the Docs](https://django-affiliate-system.readthedocs.io/)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes.\n\n## Credits\n\nCreated and maintained by [Ayodeji Akenroye](https://github.com/aayodejii).\n\n# django-affiliate-system\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive Django affiliate marketing and referral tracking system",
"version": "0.1.0a3",
"project_urls": {
"Bug Reports": "https://github.com/aayodejii/django-affiliate-system/issues",
"Documentation": "https://django-affiliate-system.readthedocs.io/",
"Homepage": "https://github.com/aayodejii/django-affiliate-system",
"Repository": "https://github.com/aayodejii/django-affiliate-system"
},
"split_keywords": [
"django",
" affiliate",
" referral",
" tracking",
" commission",
" marketing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b7d0f0a25c7c5941ffa339013c0429fdb7821796e63c7841727efdfb3026638c",
"md5": "3fe74be5b3352213971fbad1ed2e5e49",
"sha256": "f4563b3476f28eaa48821b71c12c49d701bbe1e84a3712827eb5f1d252c8add4"
},
"downloads": -1,
"filename": "django_affiliate_system-0.1.0a3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3fe74be5b3352213971fbad1ed2e5e49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 32744,
"upload_time": "2025-10-25T10:01:08",
"upload_time_iso_8601": "2025-10-25T10:01:08.237924Z",
"url": "https://files.pythonhosted.org/packages/b7/d0/f0a25c7c5941ffa339013c0429fdb7821796e63c7841727efdfb3026638c/django_affiliate_system-0.1.0a3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1eac07eb579f2ec22a2dd30ea548ed0ded2cb84f5f14fbe9e4b8d73c62a8d541",
"md5": "da34cf949660677cb9f936ad5b77feea",
"sha256": "0767b5c60722657947f9637fc70813698236fc9f522dc41b1e4594cba00c5435"
},
"downloads": -1,
"filename": "django_affiliate_system-0.1.0a3.tar.gz",
"has_sig": false,
"md5_digest": "da34cf949660677cb9f936ad5b77feea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 28951,
"upload_time": "2025-10-25T10:01:13",
"upload_time_iso_8601": "2025-10-25T10:01:13.311621Z",
"url": "https://files.pythonhosted.org/packages/1e/ac/07eb579f2ec22a2dd30ea548ed0ded2cb84f5f14fbe9e4b8d73c62a8d541/django_affiliate_system-0.1.0a3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 10:01:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aayodejii",
"github_project": "django-affiliate-system",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "django-affiliate-system"
}
JSON
