igny8/docs/audits/BILLING-SYSTEM-AUDIT-AND-REFACTOR-PLAN-20260120.md

# IGNY8 Billing System Audit + Refactor Plan

**Date:** January 20, 2026  
**Status:** Critical  
**Scope:** Billing system, payment methods, subscriptions, credits, invoices, PK (Pakistan) bank transfer flow  

---

## 1) Executive Summary

The billing system has **critical functional and architectural issues** affecting credit accuracy, manual payment approvals, invoice lifecycles, and monthly credit resets. Stripe and PayPal flows largely work, but manual approvals (especially PK bank transfer) and credit lifecycle rules are broken. Credits do not expire, and subscription credits do not reset correctly for manual renewals.

The plan below preserves all current payment methods while fixing the broken flows and making all states visible and auditable.

---

## 2) Current System Coverage (What Exists Today)

### Payment Methods (Country Rules)

| Region | Available Methods | Notes |
|---|---|---|
| Non‑PK | Stripe, PayPal | Bank transfer disabled |
| PK | Stripe, Bank Transfer | PayPal disabled |

### Core Billing Components

| Component | Purpose | Current State |
|---|---|---|
| Account status | Controls access | Active, trial, pending_payment used |
| Subscription | Plan + billing cycle | Present, but manual renewals mishandle credits |
| Invoices | Payment tracking | Present, but no type/expiry enforcement |
| Payments | Gateway/Manual transactions | Present, but approval logic incomplete |
| Credits | Single counter | No expiry, no separation |

---

## 3) Critical Issues (Audit Findings)

### Issue A — Wrong Credits Added for Manual Credit Purchases
**Impact:** Users buy a credit package (e.g., 500) but receive subscription credits (e.g., 200).  
**Cause:** Approval logic uses plan credits instead of credit package credits.

### Issue B — Manual Renewal Adds Instead of Resets
**Impact:** Monthly renewal should reset credits but instead adds to leftover balance.  
**Cause:** Manual approval uses add instead of reset.

### Issue C — No Credit Expiry / Validity Rules
**Impact:** Credits never expire. Business rule requires 1‑month validity.  
**Cause:** No expiry metadata or tasks.

### Issue D — Invoice Types Not Enforced
**Impact:** Subscription invoices and credit invoices are mixed, causing UI and logic mistakes.  
**Cause:** No explicit invoice type field and insufficient filtering.

### Issue E — No Auto‑Expiry of Pending Invoices
**Impact:** Pending invoices remain forever, creating clutter and wrong user states.  
**Cause:** No expiration field and no scheduled task to void.

---

## 4) Payment Flows (Current Behavior vs Expected)

### 4.1 Subscription Purchase (New User)

| Step | Current Behavior | Expected |
|---|---|---|
| Signup with paid plan | Account pending_payment | Correct |
| Manual payment submission | Payment pending_approval | Correct |
| Admin approval | Account active + credits added | **Should reset to plan credits** |

### 4.2 Subscription Renewal (Manual)

| Step | Current Behavior | Expected |
|---|---|---|
| Renewal invoice created | Subscription pending_renewal | Correct |
| Admin approval | Credits added | **Should reset** |

### 4.3 Credit Package Purchase (PK Manual)

| Step | Current Behavior | Expected |
|---|---|---|
| Invoice created | Pending invoice | Correct |
| Admin approval | Adds plan credits | **Should add package credits** |

### 4.4 Credit Package Purchase (Stripe/PayPal)

| Step | Current Behavior | Expected |
|---|---|---|
| Checkout | Works | Correct |
| Payment | Credits added correctly | Correct |

---

## 5) Credit System Audit

### Current Structure
- Single integer balance on Account
- No separation between subscription credits and purchased credits
- No validity period or expiry

### Required Behaviors
- Subscription credits reset monthly
- Purchased credits expire after 1 month
- Ledger always traceable for audit and reconciliation

---

## 6) Invoice System Audit

### Current Structure
- No invoice type field (implicit only)
- Pending invoices never expire
- No user cancellation for credit invoices

### Required Behaviors
- Explicit invoice_type = subscription / credit_package / custom
- Credit invoices expire after a set time (24–48 hours)
- Users can cancel pending credit invoices
- Clear separation of subscription vs credit invoices for UI and status

---

## 7) PK (Pakistan) Bank Transfer Special Case

### Must Remain Working
- Stripe still available
- PayPal hidden
- Bank details displayed in UI
- Manual payment submission works

### Required Fixes
- Manual approvals must respect invoice type
- Credit package approvals must add package credits
- Subscription approvals must reset credits
- Pending credit invoices must expire after 24 hours

---

# Part II — Refactor Plan (No Code)

## Phase 1 — Data Model Stabilization

### 1.1 Invoice Type & Expiry
Add:
- invoice_type: subscription / credit_package / custom
- expires_at: datetime
- void_reason: text

Rules:
- credit_package invoices expire after 24 hours
- subscription invoices follow grace period rules

### 1.2 Credit Buckets
Add:
- subscription_credits (monthly reset)
- purchased_credits (expires rolling 30 days)
- credits_total (computed)

---

## Phase 2 — Payment Approval Logic

### 2.1 Unified Approval Logic (Single Source)
Rules:
- If invoice_type == credit_package → add package credits
- If invoice_type == subscription → reset plan credits
- Account status updated only for subscription invoices

### 2.2 Manual Renewals
- Replace add‑credits with reset‑credits

---

## Phase 3 — Invoice Lifecycle Governance

### 3.1 Auto‑Expire Credit Invoices
- Scheduled task: void invoices past expires_at

### 3.2 User Cancellation
- Allow user to void their own pending credit invoices

---

## Phase 4 — Monthly Credit Reset + Expiry

### 4.1 Subscription Reset
- On every billing cycle, subscription credits set to plan amount

### 4.2 Purchased Credit Expiry
- Credits expire 30 days after purchase
- Expired credits removed automatically

---

## Phase 5 — Observability & Health

### Metrics to Track

| Metric | Purpose |
|---|---|
| Pending credit invoices > 24h | Detect stuck manual payments |
| Subscription renewals not resetting | Detect ledger issues |
| Credits mismatch vs ledger | Detect consistency bugs |

### Admin Visibility
- Active subscription health panel
- Manual approvals queue
- Credit expiry report

---

# Part III — Target Healthy Flow (All Methods Preserved)

## Subscription Purchase (Any Method)
1. Invoice created (type=subscription)
2. Payment processed
3. Credits reset to plan amount
4. Account active

## Subscription Renewal (Any Method)
1. Invoice created
2. Payment processed
3. Credits reset (not added)

## Credit Package Purchase
1. Invoice created (type=credit_package, expires in 24h)
2. Payment processed
3. Package credits added to purchased pool

---

# Part IV — User Visibility (Frontend)

| User State | What User Sees |
|---|---|
| Pending subscription invoice | “Pay to activate plan” view |
| Pending credit invoice | “Complete payment for credits” view |
| Credit expiry | “Expires in X days” message |
| Renewal date | “Credits reset on” message |

---

# Part V — Rollout Plan

### Step 1: Fix Approval Logic (Critical)
- Ensure credit package approvals add correct credits
- Ensure manual renewals reset credits

### Step 2: Enforce Invoice Type + Expiry
- Add explicit invoice_type and expires_at
- Run migration and update existing invoices

### Step 3: Implement Credit Validity
- Add purchased credit tracking
- Expire credits monthly

### Step 4: UI Cleanup
- Show invoice‑type specific status
- Avoid blocking account on credit invoices

---

# Final Note

This plan keeps **all payment methods working** while fixing broken credit logic, invoice lifecycle, and monthly reset rules. It also introduces explicit accounting for credit sources, enabling correct expiry and accurate audits across all payment methods and regions.