igny8/docs/20-API/BILLING-ENDPOINTS.md

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.