igny8/docs/PRE-LAUNCH/ITEM-2-CREDITS-BILLING-PRICING.md

Item 2: Credits, Billing, Pricing Logic, and Usage Limits

Priority: Critical
Target: Production Launch
Last Updated: December 11, 2025

---

Overview

Define and implement a comprehensive credit cost system, plan-based usage limits, and billing logic for all AI operations. This includes setting credit costs per function, establishing plan tiers with limits, and implementing enforcement mechanisms across backend and frontend.

---

Current Implementation Analysis

Credit System Architecture

Location: backend/igny8_core/business/billing/

Credit Models

Model	Purpose	Key Fields
CreditTransaction	Tracks all credit additions/deductions	transaction_type, amount, balance_after, description
CreditUsageLog	Detailed log per AI operation	operation_type, credits_used, cost_usd, model_used, tokens_input, tokens_output
CreditCostConfig	Admin-configurable credit costs	operation_type, credits_cost, unit, display_name

Credit Transaction Types:

• purchase - Credit purchase
• subscription - Monthly subscription renewal
• refund - Credit refund
• deduction - Usage deduction (AI operations)
• adjustment - Manual admin adjustment

Credit Service

Location: backend/igny8_core/business/billing/services/credit_service.py

Methods:

• get_credit_cost(operation_type, amount) - Calculate cost for operation
• check_credits(account, operation_type, amount) - Validate sufficient credits
• deduct_credits(account, amount, operation_type, ...) - Deduct and log
• deduct_credits_for_operation(...) - Convenience method with auto-calculation

Logic:

1. Checks database CreditCostConfig first
2. Falls back to hardcoded CREDIT_COSTS constants
3. Applies unit-based calculation (per 100 words, per image, etc.)
4. Validates sufficient balance before deduction
5. Creates both CreditTransaction and CreditUsageLog records

---

Current Credit Costs

Location: backend/igny8_core/business/billing/constants.py

Operation	Current Cost	Unit	Notes
clustering	10 credits	per request	Clusters all submitted keywords
idea_generation	15 credits	per request	Ideas for one cluster
content_generation	1 credit	per 100 words	Word-count based
image_prompt_extraction	2 credits	per content	Extract prompts from content
image_generation	5 credits	per image	Generate single image
linking	8 credits	per content	Internal linking (NEW)
optimization	1 credit	per 200 words	Content optimization (NEW)
site_structure_generation	50 credits	per site	Site blueprint (Phase 7)
site_page_generation	20 credits	per page	Page generation (Phase 7)

Legacy Aliases:

• ideas → idea_generation
• content → 3 credits fixed (legacy)
• images → image_generation
• reparse → 1 credit

Issues with Current Costs:

1. Not optimized for profitability - Costs may not reflect actual AI provider costs
2. Arbitrary values - No clear formula based on model costs, processing time, or value
3. Inconsistent granularity - Some per-request, some per-word, some per-item
4. No differentiation by quality - Same cost regardless of model quality (GPT-4 vs GPT-3.5)

---

Plan Model and Limits

Location: backend/igny8_core/auth/models.py - Plan model

Current Plan Structure

Field	Purpose	Current State
name, slug	Plan identification	✅ Implemented
price, billing_cycle	Pricing	✅ Monthly/Annual support
included_credits	Monthly credit allocation	✅ Implemented
extra_credit_price	Per-credit overage cost	✅ Default $0.01
allow_credit_topup	Can buy more credits	✅ Boolean flag
auto_credit_topup_threshold	Auto-buy trigger	✅ Optional
auto_credit_topup_amount	Auto-buy amount	✅ Optional
max_users	Users per account	✅ Implemented
max_sites	Sites per account	✅ Implemented
max_industries	Industries/sectors limit	✅ Optional
max_author_profiles	Writing styles limit	✅ Default 5

What's MISSING:

• ❌ Max keywords limit
• ❌ Max clusters limit
• ❌ Max ideas limit
• ❌ Max content pieces limit
• ❌ Max images limit
• ❌ Max tasks in queue limit
• ❌ Daily/monthly usage caps (beyond credits)
• ❌ Per-user vs per-account limits distinction

---

Account Credit Balance

Location: backend/igny8_core/auth/models.py - Account model

Field: credits (IntegerField with MinValueValidator(0))

Current Behavior:

• Credits deducted on AI operation completion
• Credit balance checked before operation starts
• InsufficientCreditsError raised if balance < required

No Implementation For:

• Credit expiration dates
• Credit rollover rules (monthly vs annual)
• Negative balance prevention (hard stop vs warning)
• Credit reserve for pending operations

---

Pricing Plan Requirements

Recommended Plan Tiers

Based on industry standards and target market:

Plan	Monthly Price	Annual Price	Included Credits	Target User
Free	$0	$0	50	Trial users, hobbyists
Starter	$29	$299 (15% off)	500	Solo creators, small blogs
Growth	$99	$1,019 (15% off)	2,000	Growing sites, agencies
Pro	$299	$3,077 (15% off)	7,500	Power users, large agencies
Enterprise	Custom	Custom	Custom	Enterprise clients

Free Plan Considerations:

• Should be marked is_internal=True to hide from public pricing
• Limits should be strict enough to encourage upgrade
• Should not include advanced features (automation, API access)

---

Usage Limits Per Plan

Proposed Limits (to be finalized):

Limit Type	Free	Starter	Growth	Pro	Enterprise
Monthly Credits	50	500	2,000	7,500	Custom
Max Users	1	2	5	15	Unlimited
Max Sites	1	3	10	50	Unlimited
Max Keywords (saved)	100	1,000	5,000	25,000	Unlimited
Max Clusters	20	100	500	2,500	Unlimited
Max Ideas (saved)	50	500	2,500	12,500	Unlimited
Max Content Pieces	25	250	1,250	6,250	Unlimited
Max Images	25	250	1,250	6,250	Unlimited
Max Queue Size	5	20	50	200	Unlimited
Automation Enabled	❌	❌	✅	✅	✅
API Access	❌	❌	✅	✅	✅
Priority Support	❌	❌	❌	✅	✅

Notes:

• "Unlimited" means no hard limit, but still subject to fair use policy
• Limits apply per account (across all sites in account)
• Deleted items don't count toward limits (soft-delete system)

---

Credit Cost Optimization Strategy

Goal: Define credit costs that:

1. Cover AI provider costs + margin
2. Are competitive with market rates
3. Encourage usage without abuse
4. Scale predictably with usage

Recommended Credit Cost Revisions

Analysis Required:

• Calculate actual AI provider costs per operation (OpenAI, Runware, etc.)
• Add 30-50% margin for infrastructure, support, and profit
• Compare with competitor pricing (Jasper, Copy.ai, Writesonic)
• Test with sample use cases to ensure plan value

Proposed Adjustments (pending analysis):

Operation	Current	Proposed	Reasoning
Clustering	10	8	Lower barrier for discovery phase
Idea Generation	15	12	Encourage ideation before writing
Content (100 words)	1	1.5	Reflect actual GPT-4 costs
Image Prompts	2	3	More complex extraction logic
Image Generation	5	6	Runware/DALL-E costs increasing
Optimization	1 per 200 words	0.5 per 100 words	Encourage optimization usage

Variable Costs by Model Quality:

• Option: Charge more for GPT-4 vs GPT-3.5, DALL-E 3 vs DALL-E 2
• Implementation: Add model_tier multiplier in get_credit_cost()

---

Required Implementation

A. Expand Plan Model with Usage Limits

File: backend/igny8_core/auth/models.py - Plan model

Add Fields:

# Content Creation Limits (NULL = unlimited)
max_keywords = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum keywords saved per account"
)
max_clusters = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum clusters per account"
)
max_ideas = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum content ideas saved per account"
)
max_content = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum content pieces per account"
)
max_images = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum images per account"
)

# Queue and Rate Limits
max_queue_size = models.IntegerField(
    default=10,
    validators=[MinValueValidator(1)],
    help_text="Maximum concurrent items in queue"
)
max_daily_ai_requests = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum AI requests per day (prevents abuse)"
)
max_monthly_content_generated = models.IntegerField(
    null=True, blank=True,
    validators=[MinValueValidator(1)],
    help_text="Maximum content pieces generated per month"
)

# Feature Access Flags
allow_automation = models.BooleanField(
    default=False,
    help_text="Enable automation wizard"
)
allow_api_access = models.BooleanField(
    default=False,
    help_text="Enable API access"
)
allow_bulk_operations = models.BooleanField(
    default=True,
    help_text="Enable bulk actions (delete, export, etc.)"
)

Migration: Create Django migration to add these fields with default NULL values

---

B. Create Limit Enforcement Service

File: backend/igny8_core/business/billing/services/limit_service.py (NEW)

Service Class: LimitService

Methods to Implement:

Method	Purpose	Returns
check_keyword_limit(account)	Check if can add more keywords	bool or raises LimitExceededError
check_cluster_limit(account)	Check if can add more clusters	bool or raises LimitExceededError
check_idea_limit(account)	Check if can add more ideas	bool or raises LimitExceededError
check_content_limit(account)	Check if can add more content	bool or raises LimitExceededError
check_image_limit(account)	Check if can add more images	bool or raises LimitExceededError
check_queue_limit(account)	Check queue capacity	bool or raises LimitExceededError
check_daily_request_limit(account)	Check daily AI request quota	bool or raises LimitExceededError
get_usage_stats(account)	Get current usage counts	dict with all counters
get_limit_stats(account)	Get limits and remaining capacity	dict with limits

Implementation Logic:

def check_keyword_limit(account):
    plan = account.plan
    if plan.max_keywords is None:
        return True  # Unlimited
    
    current_count = Keywords.objects.filter(
        account=account,
        deleted_at__isnull=True  # Exclude soft-deleted
    ).count()
    
    if current_count >= plan.max_keywords:
        raise LimitExceededError(
            f"Keyword limit reached ({plan.max_keywords}). Upgrade your plan."
        )
    
    return True

Exception: LimitExceededError (inherit from BillingException)

---

C. Integrate Limit Checks in API Views

Files to Update:

• backend/igny8_core/modules/planner/views.py - KeywordsViewSet
• backend/igny8_core/modules/planner/views.py - ClustersViewSet
• backend/igny8_core/modules/planner/views.py - ContentIdeasViewSet
• backend/igny8_core/modules/writer/views.py - TasksViewSet
• backend/igny8_core/modules/writer/views.py - ContentViewSet

Integration Points:

ViewSet	Action	Check to Add
KeywordsViewSet	create()	LimitService.check_keyword_limit(account)
KeywordsViewSet	bulk_create()	Check limit with proposed count
ClustersViewSet	create()	LimitService.check_cluster_limit(account)
ContentIdeasViewSet	create()	LimitService.check_idea_limit(account)
TasksViewSet	create()	LimitService.check_content_limit(account) + check_queue_limit()
ContentViewSet	create()	LimitService.check_content_limit(account)

Example Integration:

def create(self, request, *args, **kwargs):
    account = request.user.account
    
    # Check limit before creating
    try:
        LimitService.check_keyword_limit(account)
    except LimitExceededError as e:
        return Response({
            'error': str(e),
            'error_code': 'LIMIT_EXCEEDED',
            'upgrade_url': '/pricing'
        }, status=403)
    
    # Proceed with creation
    return super().create(request, *args, **kwargs)

---

D. Add Usage Tracking and Counter Cache

Optimization: Instead of counting records on every request, cache counts

Implementation Options:

Option 1: Add Counter Fields to Account Model

# Add to Account model
keyword_count = models.IntegerField(default=0)
cluster_count = models.IntegerField(default=0)
idea_count = models.IntegerField(default=0)
content_count = models.IntegerField(default=0)
image_count = models.IntegerField(default=0)

Update counters in signals:

• post_save signal: increment counter
• post_delete signal: decrement counter
• Periodic reconciliation task to fix drift

Option 2: Cache Usage Stats (Recommended)

Use Django cache with 5-minute TTL:

def get_cached_usage_stats(account):
    cache_key = f'usage_stats_{account.id}'
    stats = cache.get(cache_key)
    
    if stats is None:
        stats = {
            'keywords': Keywords.objects.filter(account=account, deleted_at__isnull=True).count(),
            'clusters': Clusters.objects.filter(account=account, deleted_at__isnull=True).count(),
            # ... etc
        }
        cache.set(cache_key, stats, 300)  # 5 minutes
    
    return stats

Invalidate cache on:

• Create operations
• Delete operations
• Soft-delete operations

---

E. Frontend Limit Display

1. Usage Dashboard Widget

Location: frontend/src/components/dashboard/UsageLimitsWidget.tsx (NEW)

Display:

• Current usage vs limit for each resource
• Progress bars with color coding:
  • Green: < 70% used
  • Yellow: 70-90% used
  • Red: > 90% used
• "Upgrade Plan" button when approaching limits

Example UI:

Usage & Limits
━━━━━━━━━━━━━━━━━━━━━━━━━━━
Keywords: 750 / 1,000 ████████░░ 75%
Clusters: 45 / 100    ████░░░░░░ 45%
Ideas: 380 / 500      ███████░░░ 76%
Content: 120 / 250    ████░░░░░░ 48%

[Upgrade Plan]

2. Inline Warnings

Show warnings when approaching limits:

• At 80%: Yellow badge "Approaching limit"
• At 90%: Orange warning "Near limit - Upgrade recommended"
• At 100%: Red error "Limit reached - Upgrade required"

Display in:

• Header metrics
• Page headers
• Before bulk operations
• In forms (disable submit if limit reached)

3. Create/Import Dialogs

Add limit check before showing form:

const handleCreateKeyword = () => {
  const stats = usageStats; // from API
  const limit = account.plan.max_keywords;
  
  if (limit && stats.keywords >= limit) {
    toast.error('Keyword limit reached. Upgrade your plan.');
    navigate('/settings/billing');
    return;
  }
  
  setShowCreateModal(true);
};

4. Upgrade Prompts

When limit error occurs:

• Show modal with:
  • Current plan
  • Current limit
  • Recommended plan
  • Benefits of upgrading
  • "Upgrade Now" CTA

---

F. Credit Cost Configuration UI (Admin)

Location: Django Admin or custom Admin Panel page

Feature: Allow superusers to edit credit costs without code changes

Admin Interface:

• List all operations with current costs
• Edit cost, unit, and display name
• Track change history (previous_cost field)
• Enable/disable operations
• Preview impact on sample use cases

Models Used:

• CreditCostConfig - Admin-editable costs
• Falls back to CREDIT_COSTS constants if not configured

---

Testing Requirements

Limit Enforcement Tests

Test Case	Expected Result
Create keyword at limit	Error: "Keyword limit reached"
Create keyword below limit	Success
Create 10 keywords via bulk import at limit	Error with count blocked
Delete keyword then create	Success (count decremented)
Soft-delete keyword then restore	Counts update correctly
Upgrade plan mid-session	New limits apply immediately

Credit Deduction Tests

Test Case	Expected Result
Generate content with sufficient credits	Content created, credits deducted
Generate content with insufficient credits	Error: "Insufficient credits"
Generate content at exact credit balance	Success, balance = 0
Generate multiple items in queue	Each deducts credits sequentially
Credit deduction failure mid-operation	Transaction rolled back, no partial deduction

Plan Limit Tests

Plan	Test Case	Expected Result
Free	Create 101st keyword (limit: 100)	Blocked
Starter	Create 6 queue items (limit: 5)	Blocked
Growth	Enable automation	Success (has access)
Pro	Create unlimited keywords	Success (no limit)
Enterprise	All operations	No limits enforced

---

Pricing Page Updates

Location: frontend/src/pages/marketing/Pricing.tsx

Required Elements

1. Plan Comparison Table

   • All tiers side-by-side
   • Feature checkmarks
   • Highlight "Most Popular" plan
   • Monthly/Annual toggle with savings badge

2. Usage Limits Display

   • Show key limits per plan
   • Use "Unlimited" label for null limits
   • Tooltip explanations for complex limits

3. Credit System Explanation

   • What credits are
   • How they're consumed
   • How to buy more
   • Credit rollover rules

4. FAQ Section

   • "What happens when I run out of credits?"
   • "Can I change plans mid-month?"
   • "Do unused credits roll over?"
   • "What's included in Enterprise?"

5. Calculator Widget (Optional)

   • Estimate monthly usage
   • Recommend plan based on needs
   • Show credit consumption breakdown

---

Success Metrics

• ✅ All AI operations enforce credit checks
• ✅ All create operations enforce limit checks
• ✅ Credit costs reflect actual provider costs + margin
• ✅ Plans are competitively priced
• ✅ Usage dashboard shows accurate counts
• ✅ Limit warnings prevent user frustration
• ✅ Upgrade flow is clear and frictionless
• ✅ Admin can adjust costs without code changes
• ✅ All tests pass

---

Related Files Reference

Backend

• backend/igny8_core/auth/models.py - Account, Plan models
• backend/igny8_core/business/billing/models.py - Credit models
• backend/igny8_core/business/billing/constants.py - Credit costs
• backend/igny8_core/business/billing/services/credit_service.py - Credit logic
• backend/igny8_core/business/billing/services/limit_service.py - NEW Limit enforcement
• backend/igny8_core/modules/planner/views.py - Planner API views
• backend/igny8_core/modules/writer/views.py - Writer API views

Frontend

• frontend/src/components/dashboard/UsageLimitsWidget.tsx - NEW Usage display
• frontend/src/pages/marketing/Pricing.tsx - Pricing page
• frontend/src/pages/Planner/*.tsx - Planner pages (add limit checks)
• frontend/src/pages/Writer/*.tsx - Writer pages (add limit checks)
• frontend/src/services/api.ts - API service (handle limit errors)

---

Notes

• Limits should be enforced at API level, not just UI level
• Consider "soft limits" with warnings vs "hard limits" with blocks
• Credit expiration and rollover rules need business decision
• Enterprise pricing needs custom quote system
• Monitor actual usage patterns to optimize costs and limits
• A/B test different pricing tiers to maximize conversion