# Billing Module Reference

## Purpose
Explain how billing is implemented: invoices, payments, credit packages, credit history/usage, payment methods, and limits, as exposed by billing services and API viewsets.

## Code Locations (exact paths)
- Models: `backend/igny8_core/business/billing/models.py`
- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
- API (business billing): `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/business/billing/urls.py`
- API (core billing endpoints): `backend/igny8_core/modules/billing/views.py`, `backend/igny8_core/modules/billing/urls.py`
- Plan metadata (included credits/limits): `backend/igny8_core/auth/models.py` (`Plan`, `Account`)

## High-Level Responsibilities
- Maintain credit ledger, usage logs, configurable per-operation costs, invoices, payments, credit packages, country-level payment method configs, and account-scoped payment methods.
- Expose endpoints for invoices/payments/credit packages/transactions, credit balance/usage/limits, and admin billing operations.
- Deduct or add credits atomically while recording both transactions and usage logs.
- Provide manual and (placeholder) Stripe/PayPal payment flows.

## Detailed Behavior
- Invoices (`InvoiceViewSet`):
  - `list`/`retrieve`: fetch account-scoped invoices; include totals, line items, billing period, dates.
  - `download_pdf`: returns PDF bytes from `InvoiceService.generate_pdf` (currently placeholder text payload).
- Payments (`PaymentViewSet`):
  - `list`: account-scoped payments with amounts, methods, status, invoice linkage, timestamps.
  - `available_methods`: delegates to `PaymentService.get_available_payment_methods` (country/config-driven; returns methods plus metadata).
  - `create_manual_payment`: creates a manual payment for an invoice (bank/local wallet); requires invoice_id, method, reference; rejects already-paid invoices; returns pending-approval status.
- Account payment methods (`AccountPaymentMethodViewSet`):
  - CRUD for account-level payment metadata (non-sensitive). `perform_create`/`perform_update` enforce one default by resetting others when `is_default` true or none exists.
  - `set_default` toggles default within the account.
- Credit packages (`CreditPackageViewSet`):
  - `list`: active packages with credits/price/discount/featured/sort order.
  - `purchase`: creates invoice via `InvoiceService.create_credit_package_invoice`; returns next action depending on requested payment method (`stripe`/`paypal` placeholders, manual fallback returns invoice info).
- Credit transactions (`CreditTransactionViewSet` in business billing views; also registered under `credits/transactions` in URLs): lists credit ledger entries per account.
- Core billing endpoints (`modules/billing/views.py`):
  - `CreditBalanceViewSet.list`: returns current credits, plan monthly credits, credits used this month.
  - `CreditUsageViewSet`: paginated credit usage logs with filters (operation_type, date range); `summary` aggregates by operation/model and totals (credits, USD); `limits` returns plan/account limits and usage (users/sites/etc.) based on `Plan` fields.
- Routing (`business/billing/urls.py`):
  - Routers for invoices, payments, credit packages, transactions, payment methods, and canonical credit endpoints (balance/usage/transactions). Legacy available-methods endpoint exposed at `/payment-methods/available/`.

## Data Structures / Models Involved (no code)
- `CreditTransaction`: ledger with type, amount (positive/negative), balance_after, metadata.
- `CreditUsageLog`: per-AI-operation usage with operation_type, credits_used, cost_usd, model_used, tokens, related object references, metadata.
- `CreditCostConfig`: per-operation cost config with unit, display metadata, active flag, audit of previous cost.
- `Invoice`: invoice_number, status, amounts (subtotal/tax/total), currency, billing_period, line_items JSON, subscription link, payment metadata, timestamps.
- `Payment`: status lifecycle, method (stripe/paypal/bank/local wallet/manual), provider references, manual notes/approval, failure reason, metadata.
- `CreditPackage`, `PaymentMethodConfig` (country/method availability + instructions/bank/local wallet data), `AccountPaymentMethod` (account-scoped payment metadata).
- Plan/account credits and limits: `Plan.included_credits`, `Plan.max_users/sites/industries/author_profiles`, `Account.credits`.

## Execution Flow
- Credits:
  - Operations call `CreditService.get_credit_cost` → `check_credits`/`deduct_credits` or `deduct_credits_for_operation` → updates `Account.credits`, writes `CreditTransaction` and `CreditUsageLog`.
  - Costs resolved from `CreditCostConfig` when active; otherwise constants. Units support per request, per 100/200 words, per item/image/idea.
- Invoicing/Payments:
  - Credit package purchase → invoice creation → next-action response (manual vs pending Stripe/PayPal integration).
  - Manual payment submission → `PaymentService.create_manual_payment` persists pending approval.
- Credit balance/usage:
  - Balance endpoint computes plan credits and month-to-date usage (from `CreditUsageLog`).
  - Usage endpoint filters logs; summary aggregates by operation/model and totals; limits endpoint computes plan-based limits and usage (users/sites/etc.) per account.

## Cross-Module Interactions
- AI/automation/planner/writer flows trigger credit checks/deductions through `CreditService`; usage logs can be filtered by operation_type (clustering, idea_generation, content_generation, image_generation, optimization, reparse).
- Plan limits surfaced in billing limits endpoint affect account/user/site management elsewhere.
- Invoice/payment metadata may be used by frontend billing UI; manual payments require admin follow-up.

## State Transitions
- Credits mutate `Account.credits`; ledger captures each change; usage logs accumulate per operation.
- Invoices move through statuses (`draft/pending/paid/void/uncollectible`); payments through (`pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled`).
- Credit packages and payment methods have active/default flags; cost configs can be toggled active/inactive.

## Error Handling
- Insufficient credits raise `InsufficientCreditsError`; API returns 402 when caught (e.g., content generation, credit deduct flows).
- Manual payment rejects missing fields or already-paid invoices.
- Usage/balance endpoints return empty data when account/plan missing instead of hard errors.
- Validation errors on site/sector/account scoping propagate from base viewsets and model constraints.

## Tenancy Rules
- Account scoping enforced via `AccountModelViewSet` or explicit account filtering in viewsets; all billing data is per-account.
- Payment methods, invoices, payments, transactions, usage logs, and balances are filtered to `request.user.account` (or `request.account` from middleware).
- Plan data comes from the account’s associated plan; no cross-tenant visibility.

## Billing Rules
- Credit costs configurable via `CreditCostConfig`; fallback constants apply when no config.
- Credit deductions and ledger entries are atomic; usage logs record the same operation with optional model/token metadata.
- Balance endpoint includes plan monthly credits; limits endpoint reports plan/user/site limits but does not enforce them here.

## Background Tasks / Schedulers
- None specific to billing in this module; Stripe/PayPal integrations are placeholders. Any future webhooks should persist to these models and adjust credits/invoices/payments accordingly.

## Key Design Considerations
- Credit handling is centralized in `CreditService` to keep ledger and usage logs consistent.
- Usage/balance endpoints are read-mostly, with graceful handling when plan/account data is missing.
- Manual payments support bank/local wallet flows without storing sensitive data; account payment methods store display metadata only.

## How Developers Should Work With This Module
- Use `CreditService` for all credit checks/deductions/additions; do not mutate `Account.credits` directly.
- When adding new AI operations, add `operation_type` to `CreditUsageLog.OPERATION_TYPE_CHOICES` and `CreditCostConfig` seed/constants, then use `deduct_credits_for_operation`.
- Extend payment flows by implementing Stripe/PayPal handlers in `PaymentService` and wiring webhooks to update `Payment`/`Invoice`.
- Use existing serializers/viewsets when exposing billing data; keep queries scoped to `request.account`.