igny8/docs/90-REFERENCE/BILLING-SYSTEM-MASTER.md

# IGNY8 Billing System Master Document

**Last Updated:** 2026-01-20

This document is the authoritative reference for the billing system implementation, including models, invoice lifecycle, payment flows, credit reset logic, and notification timing.

---

## 1) Core Principles

- **No hardcoded products**: Plans, credit packages, and future add-ons are data-driven.
- **Explicit invoice type**: `subscription`, `credit_package`, `addon`, `custom`.
- **Correct crediting**:
  - Subscription credits reset to **0** at cycle end.
  - Subscription credits reset to **full plan amount** on renewal/activation.
  - Credit package credits add to balance.
- **Lifecycle governance**: Credit invoices expire automatically and can be cancelled by users.
- **Auditability**: Every credit change is recorded in `CreditTransaction`.

---

## 2) Data Model Overview

### 2.1 Invoice
| Field | Purpose |
|---|---|
| `invoice_type` | `subscription`, `credit_package`, `addon`, `custom` |
| `status` | `draft`, `pending`, `paid`, `void`, `uncollectible` |
| `expires_at` | Expiry for credit invoices |
| `void_reason` | Cancellation/expiration reason |
| `line_items` | Itemized charges (product‑driven) |
| `metadata` | Compatibility + gateway context |

### 2.2 Payment
| Field | Purpose |
|---|---|
| `status` | `pending_approval`, `succeeded`, `failed`, `refunded` |
| `payment_method` | `stripe`, `paypal`, `bank_transfer`, `local_wallet`, `manual` |
| `invoice` | FK to invoice |
| `metadata` | Gateway and fulfillment details |

### 2.3 Credits
| Field | Purpose |
|---|---|
| `Account.credits` | Current balance |
| `CreditTransaction` | Immutable ledger of changes |

---

## 3) Invoice Types and Fulfillment Rules

| Invoice Type | Fulfillment | Account Status Change |
|---|---|---|
| `subscription` | Reset credits to plan amount | Activate account + subscription |
| `credit_package` | Add package credits | No status change |
| `addon` | Provision add-on entitlement | No status change |
| `custom` | No credits unless specified | No status change |

---

## 4) Flowcharts

### 4.1 Subscription Purchase (Stripe / PayPal / Bank Transfer)
```mermaid
flowchart TD
    A[User selects plan] --> B[Create subscription invoice]
    B --> C{Payment Method}
    C -->|Stripe/PayPal| D[Gateway checkout]
    D --> E[Webhook payment succeeded]
    E --> F[Invoice paid]
    F --> G[Reset credits to full plan amount]
    G --> H[Account + subscription active]

    C -->|Bank Transfer| I[User submits confirmation]
    I --> J[Payment pending_approval]
    J --> K[Admin approves]
    K --> F
```

### 4.2 Subscription Renewal (Automatic + Manual)
```mermaid
flowchart TD
    A[Billing cycle end] --> B[Reset credits to 0]
    B --> C[Create renewal invoice]
    C --> D{Auto method available?}
    D -->|Yes| E[Gateway charges]
    E --> F[Webhook payment succeeded]
    F --> G[Reset credits to full plan amount]
    G --> H[Subscription active]

    D -->|No| I[Manual payment required]
    I --> J[Invoice emailed]
    J --> K[Admin approves]
    K --> G
```

### 4.3 Credit Package Purchase (All Methods)
```mermaid
flowchart TD
    A[User selects credit package] --> B[Create credit invoice + expires_at]
    B --> C{Payment Method}
    C -->|Stripe/PayPal| D[Gateway checkout]
    D --> E[Webhook payment succeeded]
    E --> F[Add package credits]

    C -->|Bank Transfer| G[User submits confirmation]
    G --> H[Payment pending_approval]
    H --> I[Admin approves]
    I --> F
```

### 4.4 Credit Invoice Expiry
```mermaid
flowchart TD
    A[Scheduler checks pending credit invoices] --> B{expires_at <= now?}
    B -->|Yes| C[Void invoice + notify user]
    B -->|No| D[No action]
```

### 4.5 Credit Invoice Cancellation (User)
```mermaid
flowchart TD
    A[User clicks cancel] --> B{Pending credit invoice?}
    B -->|Yes| C[Set status=void, void_reason=user_cancelled]
    C --> D[Notify user]
    B -->|No| E[Reject request]
```

---

## 5) Notification Matrix (Required Emails)

| Event | Email | Timing |
|---|---|---|
| Manual payment submitted | Payment confirmation | Immediate |
| Manual payment approved | Payment approved | Immediate |
| Manual payment rejected | Payment rejected | Immediate |
| Renewal notice | Subscription renewal notice | N days before end |
| Renewal invoice | Invoice email | At renewal creation |
| Renewal reminder | Invoice reminder | Every 3 days until paid |
| Credit invoice expiring | Credit invoice expiring | 24h before expires_at |
| Credit invoice expired | Credit invoice expired | At void |
| Credit invoice cancelled | Credit invoice cancelled | Immediate |
| Payment failed | Payment failed | Immediate |
| Low credits | Low credits warning | Threshold crossing |
| Subscription expired | Subscription expired | When grace period ends |

---

## 6) Scheduled Tasks

| Task | Purpose | Schedule |
|---|---|---|
| send_renewal_notices | Renewal reminders | Daily 09:00 |
| process_subscription_renewals | Create renewal invoices | Daily 00:05 |
| send_invoice_reminders | Remind pending renewals | Daily 10:00 |
| check_expired_renewals | Expire grace period | Daily 00:15 |
| send_credit_invoice_expiry_reminders | Credit invoice expiry reminder | Daily 09:30 |
| void_expired_credit_invoices | Auto-void expired credit invoices | Daily 00:45 |
| replenish_monthly_credits | Monthly credit reset (legacy) | 1st day monthly |

---

## 7) Key Implementation Rules

1. **Invoice type drives fulfillment** (no plan/package hardcoding).
2. **Subscription credits**: reset to **0** at cycle end, then set to **full amount** on renewal.
3. **Credit packages**: add package credits only.
4. **Credit invoices**: expire automatically and are cancellable by users.
5. **Account status** only changes on **subscription invoices**.

---

## 8) Operational Verification Checklist

- Stripe/PayPal subscription purchase activates account and resets credits.
- Bank transfer subscription approval resets credits (not adds).
- Credit package approval adds package credits (not plan credits).
- Credit invoices do not block subscription state.
- Credit invoice expiry and cancellation work with emails.
- Renewal resets credits to 0 at cycle end and to full on payment.

---

## 9) Extensibility (Future Add‑ons)

- Add new `Product` types without code changes to invoice fulfillment.
- Use `invoice_type='addon'` with line items to provision entitlements.
- No plan/package hardcoding required.

---

## 10) References

- Audit: [docs/audits/BILLING-SYSTEM-AUDIT-20260120.md](docs/audits/BILLING-SYSTEM-AUDIT-20260120.md)
- Refactor Plan: [docs/audits/BILLING-SYSTEM-AUDIT-AND-REFACTOR-PLAN-20260120.md](docs/audits/BILLING-SYSTEM-AUDIT-AND-REFACTOR-PLAN-20260120.md)