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

IGNY8 Billing System Master Document

Last Updated: 2026-01-20

Primary Reference: For complete billing documentation, see 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
• Payment Gateways: PAYMENT-SYSTEM.md