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)

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)

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)

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

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)

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
• Refactor Plan: docs/audits/BILLING-SYSTEM-AUDIT-AND-REFACTOR-PLAN-20260120.md