docs/examples/invoice_pricing_examples.py

"""
Invoice Pricing Examples - Real-world pricing configurations

Examples showing how to configure different pricing models for projects.
"""

# Example 1: Tiered Pricing (Airtel Customer Service)
airtel_tiered_pricing = {
    "title": "Airtel Customer Service 2025",
    "project_type": "support",
    "service_type": "other",
    "client_id": "uuid-client",
    "contractor_id": "uuid-contractor",
    "invoice_pricing_rules": {
        "pricing_model": "tiered",
        "currency": "KES",
        "apply_per_invoice": True,  # Reset count per invoice
        "tax_rate": 16,  # 16% VAT
        "tiers": [
            {
                "tier_number": 1,
                "from_ticket": 1,
                "to_ticket": 500,
                "rate_per_ticket": 3200,
                "description": "First 500 tickets @ KES 3,200"
            },
            {
                "tier_number": 2,
                "from_ticket": 501,
                "to_ticket": 800,
                "rate_per_ticket": 2800,
                "description": "Next 300 tickets @ KES 2,800"
            },
            {
                "tier_number": 3,
                "from_ticket": 801,
                "to_ticket": None,  # Unlimited
                "rate_per_ticket": 2500,
                "description": "All remaining tickets @ KES 2,500"
            }
        ],
        "notes": "Airtel customer service project - tiered pricing per invoice"
    }
}

# Example 2: Cumulative Tiered Pricing
cumulative_tiered_pricing = {
    "title": "Safaricom FTTH Rollout",
    "project_type": "installation",
    "service_type": "ftth",
    "client_id": "uuid-client",
    "contractor_id": "uuid-contractor",
    "invoice_pricing_rules": {
        "pricing_model": "tiered",
        "currency": "KES",
        "apply_per_invoice": False,  # Cumulative across project
        "tax_rate": 16,
        "tiers": [
            {
                "tier_number": 1,
                "from_ticket": 1,
                "to_ticket": 1000,
                "rate_per_ticket": 5000,
                "description": "First 1,000 installations @ KES 5,000"
            },
            {
                "tier_number": 2,
                "from_ticket": 1001,
                "to_ticket": 5000,
                "rate_per_ticket": 4500,
                "description": "Next 4,000 installations @ KES 4,500"
            },
            {
                "tier_number": 3,
                "from_ticket": 5001,
                "to_ticket": None,
                "rate_per_ticket": 4000,
                "description": "All remaining @ KES 4,000"
            }
        ],
        "notes": "Volume discount - cumulative across entire project"
    }
}

# Example 3: Flat Rate Pricing
flat_rate_pricing = {
    "title": "Standard FTTH Installations",
    "project_type": "installation",
    "service_type": "ftth",
    "client_id": "uuid-client",
    "contractor_id": "uuid-contractor",
    "invoice_pricing_rules": {
        "pricing_model": "flat_rate",
        "currency": "KES",
        "rate_per_ticket": 5000,
        "tax_rate": 16,
        "notes": "Standard installation rate - KES 5,000 per installation"
    }
}

# Example 4: Time-Based Pricing (Consultant)
time_based_pricing = {
    "title": "Network Consulting Services",
    "project_type": "maintenance",
    "service_type": "other",
    "client_id": "uuid-client",
    "contractor_id": "uuid-contractor",
    "invoice_pricing_rules": {
        "pricing_model": "time_based",
        "currency": "USD",
        "rate_per_unit": 25,
        "rate_period": "hour",
        "tax_rate": 0,
        "notes": "Consultant hourly rate - USD 25/hour"
    }
}

# Example 5: Custom Pricing (Distance-Based)
custom_pricing = {
    "title": "Rural FTTH Project",
    "project_type": "installation",
    "service_type": "ftth",
    "client_id": "uuid-client",
    "contractor_id": "uuid-contractor",
    "invoice_pricing_rules": {
        "pricing_model": "custom",
        "currency": "KES",
        "formula": "base_rate + (distance_km * distance_rate)",
        "variables": {
            "base_rate": 3000,
            "distance_rate": 50
        },
        "tax_rate": 16,
        "notes": "Base rate + KES 50 per km from hub"
    }
}

# Example 6: No Pricing Rules (Manual Pricing)
no_pricing_rules = {
    "title": "Custom Project",
    "project_type": "installation",
    "service_type": "ftth",
    "client_id": "uuid-client",
    "contractor_id": "uuid-contractor",
    "invoice_pricing_rules": None  # Manual pricing required
}

# ============================================
# INVOICE GENERATION EXAMPLES
# ============================================

# Example: Generate Invoice with Tiered Pricing
generate_invoice_tiered = {
    "project_id": "uuid-project",
    "contractor_id": "uuid-contractor",
    "client_id": "uuid-client",
    "ticket_ids": ["uuid1", "uuid2", "..."],  # 750 tickets
    "title": "December 2025 Invoice",
    "notes": "Monthly invoice for customer service tickets"
}

# Expected Result (750 tickets with Airtel pricing):
# Tier 1: 500 tickets × 3,200 = 1,600,000 KES
# Tier 2: 250 tickets × 2,800 = 700,000 KES
# Subtotal: 2,300,000 KES
# Tax (16%): 368,000 KES
# Total: 2,668,000 KES

# Example: Generate Invoice with Flat Rate
generate_invoice_flat = {
    "project_id": "uuid-project",
    "contractor_id": "uuid-contractor",
    "client_id": "uuid-client",
    "ticket_ids": ["uuid1", "uuid2", "..."],  # 100 tickets
    "title": "January 2025 Installations"
}

# Expected Result (100 tickets @ 5,000):
# Subtotal: 500,000 KES
# Tax (16%): 80,000 KES
# Total: 580,000 KES

# ============================================
# API EXAMPLES
# ============================================

# Create Project with Tiered Pricing
"""
POST /api/v1/projects
Content-Type: application/json

{
  "title": "Airtel Customer Service 2025",
  "project_type": "support",
  "service_type": "other",
  "client_id": "uuid-client",
  "contractor_id": "uuid-contractor",
  "invoice_pricing_rules": {
    "pricing_model": "tiered",
    "currency": "KES",
    "apply_per_invoice": true,
    "tax_rate": 16,
    "tiers": [
      {
        "tier_number": 1,
        "from_ticket": 1,
        "to_ticket": 500,
        "rate_per_ticket": 3200,
        "description": "First 500 tickets"
      },
      {
        "tier_number": 2,
        "from_ticket": 501,
        "to_ticket": 800,
        "rate_per_ticket": 2800,
        "description": "Next 300 tickets"
      },
      {
        "tier_number": 3,
        "from_ticket": 801,
        "to_ticket": null,
        "rate_per_ticket": 2500,
        "description": "All remaining"
      }
    ]
  }
}
"""

# Generate Invoice (Automatic Pricing)
"""
POST /api/v1/invoices/generate
Content-Type: application/json

{
  "project_id": "uuid-project",
  "contractor_id": "uuid-contractor",
  "client_id": "uuid-client",
  "ticket_ids": ["uuid1", "uuid2", ...],
  "title": "December 2025 Invoice"
}

Response:
{
  "invoice": {
    "id": "uuid",
    "invoice_number": "INV-AIRTEL-2025-00142",
    "subtotal": 2300000.00,
    "tax_rate": 16.00,
    "tax_amount": 368000.00,
    "total_amount": 2668000.00,
    "currency": "KES",
    "line_items": [
      {
        "type": "pricing_tier",
        "description": "First 500 tickets @ KES 3,200",
        "quantity": 500,
        "unit_price": 3200.00,
        "total": 1600000.00,
        "tier_number": 1
      },
      {
        "type": "pricing_tier",
        "description": "Next 300 tickets @ KES 2,800",
        "quantity": 250,
        "unit_price": 2800.00,
        "total": 700000.00,
        "tier_number": 2
      }
    ],
    "additional_metadata": {
      "pricing_calculation": {
        "pricing_model": "tiered",
        "total_tickets": 750,
        "tiers_applied": [
          {
            "tier_number": 1,
            "from_ticket": 1,
            "to_ticket": 500,
            "tickets_in_tier": 500,
            "rate_per_ticket": 3200,
            "subtotal": 1600000
          },
          {
            "tier_number": 2,
            "from_ticket": 501,
            "to_ticket": 750,
            "tickets_in_tier": 250,
            "rate_per_ticket": 2800,
            "subtotal": 700000
          }
        ]
      }
    }
  }
}
"""

# Update Project Pricing Rules
"""
PUT /api/v1/projects/{project_id}
Content-Type: application/json

{
  "invoice_pricing_rules": {
    "pricing_model": "flat_rate",
    "currency": "KES",
    "rate_per_ticket": 4500,
    "tax_rate": 16,
    "notes": "Updated to flat rate"
  }
}
"""

# Remove Pricing Rules (Switch to Manual)
"""
PUT /api/v1/projects/{project_id}
Content-Type: application/json

{
  "invoice_pricing_rules": null
}
"""