igny8/master-docs/10-backend/billing/PRICING-AND-PLANS.md

Pricing and Plans

Purpose

Describe how plans and pricing are represented in the backend and how plan data is used for credits and limits.

Code Locations (exact paths)

• Plan and account fields: backend/igny8_core/auth/models.py (Plan, Account)
• Billing limits endpoint: backend/igny8_core/modules/billing/views.py (CreditUsageViewSet.limits)
• Credit balance endpoint: backend/igny8_core/modules/billing/views.py (CreditBalanceViewSet)

High-Level Responsibilities

• Define subscription plans with included credits, billing cycle, pricing, feature flags, account limits, and Stripe metadata.
• Attach plans to accounts and expose plan-based limits and credits to billing endpoints.
• Keep credit computations aligned with included_credits via Plan.get_effective_credits_per_month.

Detailed Behavior

• Plan fields:
  • Pricing: price, billing_cycle (monthly/annual), extra_credit_price, allow_credit_topup, optional auto-topup thresholds/amounts.
  • Credits: included_credits (preferred) with legacy credits_per_month fallback via get_effective_credits_per_month.
  • Limits: max_users, max_sites, max_industries, max_author_profiles.
  • Stripe: stripe_product_id, stripe_price_id.
  • Features: JSON features list; is_active flag.
  • Validation ensures max_sites >= 1, included_credits >= 0.
• Account fields:
  • plan FK, credits balance, status (active/suspended/trial/cancelled), billing contact/address fields, tax_id, retention days, Stripe customer id.
  • Soft-delete guard prevents deleting system accounts.
• Limits computation (billing limits endpoint):
  • Calculates current usage counts (users, sites, industries, author profiles) and returns alongside plan limits.
  • Returns empty limits when account or plan is missing to keep UI resilient.
• Credit balance:
  • Balance endpoint includes plan_credits_per_month using Plan.get_effective_credits_per_month.

Data Structures / Models Involved (no code)

• Plan, Account (plan attachment, credits, limits, billing info).

Execution Flow

• Account creation/association sets plan; credit balance endpoints read plan credits and account credits.
• Limits endpoint reads plan limits and computes current usage counts per account.
• Credit usage/deductions run against Account.credits; top-ups/invoices handled through billing services.

Cross-Module Interactions

• Billing endpoints surface plan credits and limits; credit cost/deductions happen in billing services.
• Automation start checks Account.credits but not plan limits; plan status enforced in AccountContextMiddleware (requires active plan).

State Transitions

• Plan activation toggles is_active; account plan changes immediately affect limits/balance reporting.
• Account status/plan changes enforced at middleware for access gating.

Error Handling

• Plan validation errors for invalid limits/credits on save; billing endpoints return empty limits when plan/account missing instead of failing.

Tenancy Rules

• Plans are global; accounts reference a single plan. All limit calculations are per account.

Billing Rules

• Credits included per plan reported via balance endpoint; extra credit price/top-up fields are present but actual purchase flows are through credit packages/invoices (not auto-charging in code shown).

Background Tasks / Schedulers

• None specific to plans; any subscription renewal logic would generate invoices/payments via billing services (not implemented here).

Key Design Considerations

• included_credits supersedes legacy credits_per_month; keep get_effective_credits_per_month for backward compatibility.
• Limits are informational in the billing module; enforcement must occur in the respective domains if required.

How Developers Should Work With This Module

• When adding new plan features or limits, extend Plan fields and ensure billing limits endpoint surfaces them.
• Use get_effective_credits_per_month wherever plan credits are displayed or calculated.
• Keep plan validation consistent (non-negative credits, minimum site/user counts).