# IGNY8 Billing System Master Document

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

> **Primary Reference:** For complete billing documentation, see [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)

This document provides a summary of the billing system implementation.

---

## 1) Core Principles

- **Two-Pool Credit System:**
  - `account.credits` = Plan credits (reset on renewal)
  - `account.bonus_credits` = Purchased credits (NEVER expire, NEVER reset)
- **Credit Usage Priority:** Plan credits used FIRST, bonus credits only when plan credits = 0
- **No hardcoded products**: Plans, credit packages, and future add-ons are data-driven.
- **Explicit invoice type**: `subscription`, `credit_package`, `addon`, `custom`.
- **Correct crediting**:
  - Subscription: reset plan credits to **full plan amount** on payment (bonus untouched)
  - Credit package: add to **bonus_credits** only (never plan credits)
- **Renewal Grace Period:** 7 days
- **Credit Reset on Non-Payment:** 24 hours after renewal (Day +1), plan credits → 0
- **Auditability**: Every credit change is recorded in `CreditTransaction`.

---

## 2) Two-Pool Credit System

| Pool | Field | Source | Behavior |
|------|-------|--------|----------|
| Plan Credits | `account.credits` | Subscription plan | Reset to plan amount on renewal payment, reset to 0 if unpaid after 24h |
| Bonus Credits | `account.bonus_credits` | Credit packages | NEVER expire, NEVER reset, only deducted after plan credits = 0 |

### Credit Deduction Priority
1. Deduct from `credits` (plan) first
2. Only when `credits = 0`, deduct remainder from `bonus_credits`

---

## 3) Renewal Workflow (Simplified)

### Stripe/PayPal (Auto-Pay) - Industry Standard
- **No advance notice** (like Netflix, Spotify)
- Day 0: Auto-charge attempt
- If success: Receipt email + credits reset to plan amount
- If failed: Retry notification, Stripe retries 4x over 7 days
- Day +7: Expired if all retries fail

### Bank Transfer (Manual)
- **Day -3:** Invoice created + Email sent
- **Day 0:** Renewal day reminder (if unpaid)
- **Day +1:** Urgent reminder + credits reset to 0
- **Day +7:** Subscription expired

---

## 4) Scheduled Tasks (Updated)

| Task | Purpose | Schedule |
|------|---------|----------|
| `create_bank_transfer_invoices` | Invoice 3 days before (bank transfer only) | Daily 09:00 |
| `process_subscription_renewals` | Auto-pay renewals (Stripe/PayPal) | Daily 00:05 |
| `send_renewal_day_reminders` | Day 0 reminder (bank transfer) | Daily 10:00 |
| `send_day_after_reminders` | Day +1 urgent reminder + credit reset | Daily 09:15 |
| `check_expired_renewals` | Expire after 7-day grace | Daily 00:15 |
| `send_credit_invoice_expiry_reminders` | Credit invoice reminder | Daily 09:30 |
| `void_expired_credit_invoices` | Auto-void credit invoices (48h) | Daily 00:45 |

---

## 5) Invoice Types and Fulfillment

| Invoice Type | Credits Action | Account Status |
|--------------|----------------|----------------|
| `subscription` | Reset plan credits to plan amount | Activate account + subscription |
| `credit_package` | Add to **bonus_credits** | No status change |
| `addon` | Provision entitlement | No status change |
| `custom` | As specified | No status change |

---

## 6) Key Implementation Rules

1. **Two pools:** `credits` (plan) + `bonus_credits` (purchased)
2. **Deduction order:** Plan credits first, then bonus credits
3. **Subscription payment:** Reset plan credits to full amount (bonus untouched)
4. **Credit package payment:** Add to bonus_credits only
5. **No payment 24h:** Plan credits → 0, bonus credits unchanged
6. **Late payment:** Plan credits restored to full amount

---

## 7) Quick Reference

### Payment Method by Country
| Country | Stripe | PayPal | Bank Transfer |
|---------|--------|--------|---------------|
| Pakistan (PK) | ✅ | ❌ | ✅ |
| Others | ✅ | ✅ | ❌ |

### Credit Reset Summary
| Event | Plan Credits | Bonus Credits |
|-------|--------------|---------------|
| Payment success | Reset to plan amount | No change |
| No payment (24h) | Reset to 0 | No change |
| Late payment | Reset to plan amount | No change |

---

## References

- Complete Documentation: [BILLING-PAYMENTS-COMPLETE.md](../10-MODULES/BILLING-PAYMENTS-COMPLETE.md)
- Payment Gateways: [PAYMENT-SYSTEM.md](PAYMENT-SYSTEM.md)