Remote Sales Team Commission Tracking Tool for Distributed Sales Operations 2026

from datetime import datetime
from decimal import Decimal
from dataclasses import dataclass
from typing import Optional
import asyncio

@dataclass
class CommissionConfig:
    base_rate: Decimal
    region_multiplier: Decimal
    tier_bonus: Decimal
    currency: str

async def calculate_commission(
    deal_amount: Decimal,
    config: CommissionConfig,
    target_currency: str,
    exchange_rate: Decimal
) -> Decimal:
    """Calculate commission with regional and tier adjustments."""

    # Apply base rate and regional multiplier
    base_commission = deal_amount * config.base_rate * config.region_multiplier

    # Add tier bonus
    total_commission = base_commission + config.tier_bonus

    # Convert to target currency
    converted = total_commission * exchange_rate

    return converted.quantize(Decimal('0.01'))

async def process_deal_commission(
    deal_id: str,
    rep_id: str,
    config: CommissionConfig
) -> dict:
    """Process a single deal and record commission."""

    # Fetch deal and current exchange rate
    deal = await fetch_deal(deal_id)
    exchange_rate = await get_exchange_rate(
        deal['currency'],
        config.currency
    )

    # Calculate commission
    commission_amount = await calculate_commission(
        Decimal(str(deal['amount'])),
        config,
        config.currency,
        exchange_rate
    )

    # Record commission
    commission_id = await insert_commission(
        deal_id=deal_id,
        rep_id=rep_id,
        base_amount=deal['amount'] * config.base_rate,
        adjusted_amount=commission_amount,
        currency=config.currency,
        exchange_rate=exchange_rate
    )

    return {'commission_id': commission_id, 'amount': commission_amount}

async def get_exchange_rate(from_currency: str, to_currency: str) -> Decimal:
    """Fetch exchange rate with caching."""

    cache_key = f"{from_currency}_{to_currency}"

    if cache_key in rate_cache:
        cached_rate, cached_time = rate_cache[cache_key]
        if (datetime.utcnow() - cached_time).seconds < 3600:
            return cached_rate

    # Fetch from API (example structure)
    async with aiohttp.ClientSession() as session:
        async with session.get(
            f"https://api.exchangerate.host/latest",
            params={'base': from_currency, 'symbols': to_currency}
        ) as response:
            data = await response.json()
            rate = Decimal(str(data['rates'][to_currency]))

    rate_cache[cache_key] = (rate, datetime.utcnow())
    return rate

from fastapi import FastAPI, Depends, HTTPException

app = FastAPI()

@app.get("/reps/{rep_id}/commissions")
async def get_rep_commissions(
    rep_id: str,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None
):
    """Fetch commission history for a sales rep."""

    query = "SELECT * FROM commissions WHERE rep_id = $1"
    params = [rep_id]

    if start_date:
        query += " AND calculated_at >= $2"
        params.append(start_date)
    if end_date:
        query += " AND calculated_at <= $3"
        params.append(end_date)

    query += " ORDER BY calculated_at DESC"

    return await db.fetch_all(query, *params)

@app.get("/commissions/summary")
async def get_commission_summary(
    region: Optional[str] = None,
    period: str = 'month'
):
    """Generate commission summary for reporting."""

    date_trunc = {
        'day': 'day',
        'week': 'week',
        'month': 'month',
        'quarter': 'quarter'
    }[period]

    query = """
        SELECT
            sr.region,
            DATE_TRUNC(%s, c.calculated_at) as period,
            COUNT(*) as deal_count,
            SUM(c.adjusted_amount) as total_commission
        FROM commissions c
        JOIN sales_reps sr ON c.rep_id = sr.id
        WHERE c.status = 'paid'
        GROUP BY sr.region, DATE_TRUNC(%s, c.calculated_at)
        ORDER BY period DESC, sr.region
    """

    return await db.fetch_all(query, date_trunc, date_trunc)

from fastapi import Request
import hmac
import hashlib

@app.post("/webhooks/crm")
async def handle_crm_webhook(request: Request):
    """Process deal closed events from CRM."""

    # Verify webhook signature
    signature = request.headers.get('X-Webhook-Signature')
    payload = await request.body()

    if not verify_signature(signature, payload):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()

    if event['type'] == 'deal_closed':
        rep = await get_rep_by_email(event['rep_email'])
        config = await get_commission_config(rep['region'])

        await process_deal_commission(
            deal_id=event['deal_id'],
            rep_id=rep['id'],
            config=config
        )

    return {"status": "processed"}

def verify_signature(signature: str, payload: bytes) -> bool:
    """Verify CRM webhook signature."""
    expected = hmac.new(
        os.environ['WEBHOOK_SECRET'],
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

from datetime import datetime, timedelta
import asyncpg

async def process_pending_payouts():
    """Process commissions ready for payout."""

    # Find commissions pending for more than 7 days
    query = """
        SELECT c.*, sr.email, sr.name, sr.currency
        FROM commissions c
        JOIN sales_reps sr ON c.rep_id = sr.id
        WHERE c.status = 'pending'
        AND c.calculated_at < NOW() - INTERVAL '7 days'
    """

    pending = await db.fetch_all(query)

    for commission in pending:
        # Generate payout file or call payment API
        await create_payout_record(commission)
        await update_commission_status(commission['id'], 'processing')

    return {'processed': len(pending)}