Reseller Module Documentation

Purpose

The Reseller module serves as a comprehensive sales management system that provides:

• Reseller Management: Registration, verification, and tier-based management
• Commission Tracking: Sophisticated commission calculation and tracking
• Earnings Management: Payout processing, invoice generation, and tax handling
• Performance Analytics: Sales metrics, conversion tracking, and leaderboards
• Marketing Tools: Referral links, campaign tracking, and promotional materials

App/reseller/
├── earnings/                   # Earnings sub-module (commission system)
│   ├── models/                 # Earnings-specific models
│   │   ├── base.py             # Base models and choices
│   │   ├── reseller.py         # Reseller profile model
│   │   ├── commission.py       # Commission tracking model
│   │   ├── invoice.py          # Invoice generation model
│   │   └── payout.py           # Payout management model
│   ├── services/               # Earnings business logic
│   │   ├── base.py             # Base service class
│   │   ├── reseller_service.py # Reseller management service
│   │   ├── commission_service.py # Commission calculation service
│   │   ├── invoice_service.py   # Invoice generation service
│   │   └── payout_service.py    # Payout processing service
│   ├── repositories/           # Earnings data access layer
│   │   ├── base.py             # Base repository class
│   │   ├── reseller_repository.py
│   │   ├── commission_repository.py
│   │   ├── invoice_repository.py
│   │   └── payout_repository.py
│   ├── forms/                  # Earnings-related forms
│   │   ├── profile_forms.py    # Reseller profile forms
│   │   ├── invoice_forms.py    # Invoice generation forms
│   │   └── payout_forms.py     # Payout request forms
│   └── api/                    # Earnings API endpoints
│       ├── urls.py             # Earnings API routing
│       └── views.py            # Earnings API views
├── api/                        # Main reseller API endpoints
│   └── v1/                     # API version 1
│       ├── serializers/        # API serializers
│       │   └── reseller_serializers.py
│       ├── views/              # API view controllers
│       │   └── reseller_views.py
│       └── urls.py             # API URL routing
├── views/                      # Web interface views
│   └── profile_views.py        # Reseller profile management views
├── management/                 # Django management commands
│   └── commands/               # Reseller-specific commands
│       ├── regenerate_partner_codes.py
│       └── update_partner_codes.py
├── migrations/                 # Database migrations
├── tests/                      # Unit and integration tests
├── utils.py                    # Utility functions
├── base_views.py               # Base view classes
├── context_processors.py      # Template context processors
├── permissions.py              # Custom permissions
├── urls.py                     # Main reseller URL routing
└── views.py                    # Legacy view functions

Reseller Profile System

Commission System

Payout System

Core Models

Reseller Model

class Reseller(TimeStampedModel):
    # User relationship
    user = models.OneToOneField(User, on_delete=models.CASCADE, related_name='reseller_profile')
    
    # Reseller type (Individual/Business)
    reseller_type = models.CharField(max_length=20, choices=ResellerType.choices)
    
    # Company information
    company_name = models.CharField(max_length=255, blank=True, null=True)
    company_website = models.URLField(blank=True, null=True)
    company_description = models.TextField(blank=True)
    
    # Contact information
    phone_number = models.CharField(max_length=20)
    address = models.TextField()
    city = models.CharField(max_length=100)
    country = models.CharField(max_length=100)
    
    # Reseller details
    referral_code = models.CharField(max_length=50, unique=True, db_index=True)
    tier = models.CharField(max_length=20, choices=TierChoices.choices)
    commission_rate = models.DecimalField(max_digits=5, decimal_places=2)
    
    # Financial information
    payment_method = models.CharField(max_length=50)
    bank_account_name = models.CharField(max_length=255)
    bank_account_number = models.CharField(max_length=100)
    paypal_email = models.EmailField()
    
    # Status and metrics
    is_active = models.BooleanField(default=True)
    is_verified = models.BooleanField(default=False)
    total_sales = models.DecimalField(max_digits=12, decimal_places=2)
    total_commission_earned = models.DecimalField(max_digits=12, decimal_places=2)
    pending_commission = models.DecimalField(max_digits=12, decimal_places=2)

Commission Model

class Commission(TimeStampedModel):
    reseller = models.ForeignKey(Reseller, on_delete=models.CASCADE, related_name='commissions')
    
    # Transaction details
    transaction_reference = models.CharField(max_length=100, unique=True)
    client_name = models.CharField(max_length=255)
    client_email = models.EmailField()
    product_name = models.CharField(max_length=255)
    
    # Financial details
    sale_amount = models.DecimalField(max_digits=10, decimal_places=2)
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    commission_rate = models.DecimalField(max_digits=5, decimal_places=2)
    tier_bonus = models.DecimalField(max_digits=10, decimal_places=2)
    
    # Status and dates
    status = models.CharField(max_length=10, choices=CommissionStatusChoices.choices)
    calculation_date = models.DateTimeField(auto_now_add=True)
    approval_date = models.DateTimeField(null=True, blank=True)
    paid_date = models.DateTimeField(null=True, blank=True)
    
    # Relationships
    invoice = models.ForeignKey('Invoice', on_delete=models.SET_NULL, null=True)
    payout = models.ForeignKey('Payout', on_delete=models.SET_NULL, null=True)

Tier System

class TierChoices(models.TextChoices):
    BRONZE = 'bronze', 'Bronze (10% commission)'
    SILVER = 'silver', 'Silver (15% commission)'  
    GOLD = 'gold', 'Gold (20% commission)'
    PLATINUM = 'platinum', 'Platinum (25% commission)'

# Tier upgrade thresholds
TIER_THRESHOLDS = {
    'BRONZE': 0,          # Entry level
    'SILVER': 5000,       # $5,000 in sales
    'GOLD': 15000,        # $15,000 in sales  
    'PLATINUM': 50000,    # $50,000 in sales
}

Reseller API Endpoints

Profile Management

Commission and Earnings

Analytics and Reporting

Core Services

Reseller Management Service

• create_reseller_profile(user, profile_data): Create new reseller profile
• update_tier(reseller_id): Automatically update reseller tier based on sales
• verify_reseller(reseller_id, verification_data): Process KYC verification
• generate_referral_code(user_id): Generate unique referral code
• deactivate_reseller(reseller_id, reason): Deactivate reseller account

Commission Calculation Service

• calculate_commission(sale_amount, reseller_id, product_id): Calculate commission for a sale
• apply_tier_bonus(commission, reseller_tier): Apply tier-based bonus
• process_sale_commission(transaction_data): Process commission for completed sale
• approve_commission(commission_id): Approve pending commission
• bulk_approve_commissions(commission_ids): Batch approve commissions

Payout Processing Service

• create_payout_request(reseller_id, amount, payment_method): Create payout request
• validate_payout_request(payout_request): Validate payout eligibility
• process_payout(payout_id): Process approved payout
• generate_payout_invoice(payout_id): Generate invoice for payout
• update_payout_status(payout_id, status): Update payout status

Analytics Service

• get_reseller_performance(reseller_id, period): Get performance metrics
• calculate_conversion_rates(reseller_id): Calculate conversion rates
• generate_leaderboard(period, metric): Generate reseller leaderboard
• get_earnings_summary(reseller_id): Get earnings summary

Referral Code Generation

The platform uses a sophisticated partner code system for tracking referrals:

Code Structure

# Partner code format: PREFIX-USERPART-CHECKSUM
# Example: LXN-U12345-A7B

def generate_partner_code(user_id):
    prefix = "LXN"  # Lixnet prefix
    user_part = f"U{user_id:05d}"  # User ID with padding
    checksum = calculate_checksum(user_part)  # Collision prevention
    return f"{prefix}-{user_part}-{checksum}"

Management Commands

• regenerate_partner_codes: Regenerate all partner codes (admin use)
• update_partner_codes: Update partner codes with new format

Tracking and Attribution

• URL Parameters: ?ref=LXN-U12345-A7B
• Cookie Tracking: 30-day attribution window
• Database Logging: All referral clicks and conversions logged
• Multi-touch Attribution: First-click and last-click tracking

Adding New Reseller Features

1. Earnings Sub-module: If feature involves commissions/payouts, add to earnings/
2. Service Layer: Implement business logic in appropriate service class
3. Repository Pattern: Use repository pattern for data access
4. API Endpoints: Follow RESTful conventions for new endpoints
5. Permissions: Implement proper access controls using custom permissions
6. Testing: Write comprehensive tests for commission calculations

Commission Calculation Guidelines

• Precision: Use Decimal type for all financial calculations
• Atomic Operations: Wrap commission calculations in database transactions
• Audit Trail: Log all commission calculations and changes
• Tier Updates: Automatically trigger tier updates after sales
• Validation: Validate all commission calculations before saving

Security Considerations

• Financial Data: Encrypt sensitive financial information
• Access Control: Resellers can only access their own data
• Payout Validation: Multiple validation layers for payout requests
• Fraud Detection: Monitor for suspicious patterns in referrals
• Rate Limiting: Implement rate limiting for API endpoints