How to Create Automated Billing Dispute Resolution Workflows

Billing disputes handled poorly lose clients. I built a system to automate billing dispute resolution workflows that captures disputes, routes them to the right team, tracks resolution, and ensures every client gets a response within SLA.

Structured resolution. No disputes falling into a black hole.

What You Need Before Starting

• Python 3.8+
• Invoice and billing database
• Dispute tracking database
• Notification system

Step 1: Capture Disputes

import sqlite3
from datetime import datetime, timedelta

def init_dispute_db(db_path="disputes.db"):
    conn = sqlite3.connect(db_path)
    conn.execute("""
        CREATE TABLE IF NOT EXISTS disputes (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            invoice_number TEXT,
            client_id TEXT,
            dispute_type TEXT,
            description TEXT,
            amount_disputed REAL,
            status TEXT DEFAULT 'open',
            assigned_to TEXT,
            sla_deadline TEXT,
            created_at TEXT,
            resolved_at TEXT,
            resolution TEXT
        )
    """)
    conn.commit()
    return conn

def create_dispute(conn, invoice_number, client_id, dispute_type, description, amount):
    sla = (datetime.now() + timedelta(days=5)).strftime("%Y-%m-%d")
    conn.execute(
        "INSERT INTO disputes (invoice_number, client_id, dispute_type, description, amount_disputed, sla_deadline, created_at) VALUES (?,?,?,?,?,?,?)",
        (invoice_number, client_id, dispute_type, description, amount, sla, datetime.now().isoformat())
    )
    conn.commit()
    return conn.execute("SELECT last_insert_rowid()").fetchone()[0]

Step 2: Route Based on Type

ROUTING_RULES = {
    "overcharge": {"team": "billing", "auto_check": True},
    "duplicate": {"team": "billing", "auto_check": True},
    "service_issue": {"team": "account_management", "auto_check": False},
    "contract_dispute": {"team": "legal", "auto_check": False},
    "unknown_charge": {"team": "billing", "auto_check": True}
}

def route_dispute(conn, dispute_id, dispute_type):
    rule = ROUTING_RULES.get(dispute_type, ROUTING_RULES["unknown_charge"])

    if rule["auto_check"]:
        result = auto_check_dispute(conn, dispute_id)
        if result.get("auto_resolved"):
            return result

    conn.execute("UPDATE disputes SET assigned_to=? WHERE id=?", (rule["team"], dispute_id))
    conn.commit()
    return {"assigned_to": rule["team"]}

Step 3: Auto-Check Common Disputes

def auto_check_dispute(conn, dispute_id):
    dispute = conn.execute(
        "SELECT invoice_number, dispute_type, amount_disputed FROM disputes WHERE id=?",
        (dispute_id,)
    ).fetchone()

    invoice_num, dtype, amount = dispute

    if dtype == "duplicate":
        dupes = conn.execute(
            "SELECT COUNT(*) FROM invoices WHERE invoice_number=? AND status='paid'",
            (invoice_num,)
        ).fetchone()[0]
        if dupes > 0:
            resolve_dispute(conn, dispute_id, "Confirmed duplicate. Credit note issued.")
            return {"auto_resolved": True, "action": "credit_note"}

    return {"auto_resolved": False}

def resolve_dispute(conn, dispute_id, resolution):
    conn.execute(
        "UPDATE disputes SET status='resolved', resolution=?, resolved_at=? WHERE id=?",
        (resolution, datetime.now().isoformat(), dispute_id)
    )
    conn.commit()

Step 4: Monitor SLA Compliance

def check_sla_breaches(conn):
    today = datetime.now().strftime("%Y-%m-%d")
    breaches = conn.execute(
        "SELECT id, invoice_number, client_id, sla_deadline FROM disputes WHERE status='open' AND sla_deadline < ?",
        (today,)
    ).fetchall()

    for dispute_id, inv, client, deadline in breaches:
        print(f"SLA BREACH: Dispute #{dispute_id} for invoice {inv} (deadline was {deadline})")

    return len(breaches)

Step 5: Generate Resolution Report

def dispute_report(conn, days=30):
    cutoff = (datetime.now() - timedelta(days=days)).isoformat()
    total = conn.execute("SELECT COUNT(*) FROM disputes WHERE created_at > ?", (cutoff,)).fetchone()[0]
    resolved = conn.execute("SELECT COUNT(*) FROM disputes WHERE status='resolved' AND created_at > ?", (cutoff,)).fetchone()[0]

    report = f"# Billing Disputes ({days} days)\n\n"
    report += f"Total: {total} | Resolved: {resolved} | Open: {total - resolved}\n"
    report += f"Resolution rate: {round(resolved/total*100) if total else 0}%\n"
    return report

What to Build Next

Add root cause analysis that groups disputes by type and identifies systemic billing issues. If 20% of disputes are "overcharge" on the same service, your pricing or billing configuration needs fixing. Fix the source, not just the symptoms.

Related Reading

• Building Your First Automation: A Complete Guide - automation fundamentals
• The Feedback Loop That Powers Everything - dispute feedback loops
• How to Audit Your Operations for AI Opportunities - finding billing process issues