# Billing Endpoints

## Purpose
Detail billing API endpoints for invoices, payments, credit packages, transactions, payment methods, and credit balance/usage.

## Code Locations (exact paths)
- Routing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
- Views: `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/modules/billing/views.py`
- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`

## High-Level Responsibilities
- Expose billing resources (invoices, payments, credit packages, payment methods, credit transactions).
- Provide credit balance/usage/limits endpoints.
- Support manual payment submission and available payment methods lookup.

## Detailed Behavior
- Base paths:
  - `/api/v1/billing/` (business billing views via router)
  - `/api/v1/admin/` (admin billing URLs)
  - `/api/v1/billing/credits/...` (balance/usage/transactions aliases)
- Invoice endpoints (`InvoiceViewSet`):
  - `GET /invoices/` list account invoices (status filter optional).
  - `GET /invoices/{id}/` invoice detail.
  - `GET /invoices/{id}/download_pdf/` returns PDF bytes (placeholder).
- Payment endpoints (`PaymentViewSet`):
  - `GET /payments/` list payments (status filter optional).
  - `GET /payment-methods/available/` returns available methods (country/config driven).
  - `POST /payments/manual/` submit manual payment for an invoice (requires invoice_id, payment_method, transaction_reference; rejects already paid).
- Account payment methods (`AccountPaymentMethodViewSet`):
  - CRUD at `/payment-methods/`; `POST /payment-methods/{id}/set_default/` toggles default for the account.
- Credit packages (`CreditPackageViewSet`):
  - `GET /credit-packages/` list active packages.
  - `POST /credit-packages/{id}/purchase/` creates invoice and returns next_action (Stripe/PayPal placeholders; manual fallback returns invoice info).
- Credit transactions (`CreditTransactionViewSet`):
  - `GET /transactions/` ledger of credit changes; also registered under `/credits/transactions/`.
- Credit balance/usage/limits (`modules/billing/views.py`):
  - `GET /credits/balance/` returns credits, plan monthly credits, month-to-date credits used.
  - `GET /credits/usage/` returns paginated usage logs with filters; `GET /credits/usage/summary/` aggregates by operation/model and totals; `GET /credits/usage/limits/` returns plan/account limits and usage counts.
- Permissions/tenancy: authenticated users; account-scoped querysets; viewsets rely on `request.account` or `request.user.account`.

## Data Structures / Models Involved (no code)
- `Invoice`, `Payment`, `CreditPackage`, `CreditTransaction`, `AccountPaymentMethod`, `PaymentMethodConfig`, `CreditUsageLog`, `CreditCostConfig`, `Account`, `Plan`.

## Execution Flow
- Router dispatch → viewset → service calls (invoice/payment/credit) → DB updates → unified responses. Balance/usage endpoints compute aggregates on demand.

## Cross-Module Interactions
- Credit costs/checks used by writer/automation AI flows; balances/usage reflect those deductions.
- Plan limits surfaced in limits endpoint relate to account management in auth/account domains.

## State Transitions
- Invoices: draft/pending/paid/void/uncollectible; Payments: pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled; Credits balance changes via transactions.

## Error Handling
- Manual payment: 400 on missing fields or already-paid invoice.
- Credit operations: 402 returned by upstream callers on `InsufficientCreditsError`.
- Balance/usage: returns zeros/empty when account/plan missing.

## Tenancy Rules
- All billing data filtered by account; no cross-tenant access. Default viewsets inherit account scoping from base classes.

## Billing Rules
- Credit costs come from `CreditCostConfig` or constants; deductions recorded in ledger + usage logs.
- Available methods and packages are filtered by active flags/config.

## Background Tasks / Schedulers
- None specific; Stripe/PayPal integrations are placeholders; any future webhooks should update invoices/payments/credits accordingly.

## Key Design Considerations
- Ledger + usage logs kept in sync via `CreditService`.
- Manual payment flow avoids storing sensitive data; account payment methods store metadata only.

## How Developers Should Work With This Module
- Use `CreditService` for credit math; do not mutate balances directly.
- Implement Stripe/PayPal flows in `PaymentService` if adding gateways; wire webhooks to update models.
- Keep account scoping on all queries; reuse existing viewsets for new billing features.