517 lines
14 KiB
Markdown
517 lines
14 KiB
Markdown
# Credit System
|
||
|
||
**Last Verified:** January 10, 2026
|
||
**Status:** ✅ Complete (v1.7.1 - Image Generation Credits)
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
IGNY8 uses a unified credit system where all AI operations consume credits from a single balance. Plan limits are simplified to 4 hard/monthly limits only.
|
||
|
||
---
|
||
|
||
## Credit Flow (Verified Architecture)
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ CREDIT FLOW │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Plan.included_credits = Monthly allocation (e.g., 10,000) │
|
||
│ ↓ (Added on subscription renewal/approval) │
|
||
│ Account.credits = Current balance (real-time, decremented) │
|
||
│ ↓ (Decremented on each AI operation) │
|
||
│ CreditTransaction = Log of all credit changes │
|
||
│ CreditUsageLog = Detailed operation tracking │
|
||
│ │
|
||
│ THESE ARE NOT PARALLEL - They serve different purposes: │
|
||
│ • Plan.included_credits = "How many credits per month" │
|
||
│ • Account.credits = "How many credits you have RIGHT NOW" │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Where credits are added to Account.credits:**
|
||
1. `billing/views.py` - When manual payment is approved
|
||
2. `payment_service.py` - When credit package purchased
|
||
3. `credit_service.py` - Generic `add_credits()` method
|
||
|
||
---
|
||
|
||
## Simplified Limits (v1.5.0)
|
||
|
||
### Hard Limits (Never Reset)
|
||
|
||
| Limit | Plan Field | Account Field | Description |
|
||
|-------|------------|---------------|-------------|
|
||
| Sites | `max_sites` | (count of Site objects) | Maximum sites per account |
|
||
| Users | `max_users` | (count of User objects) | Maximum team members |
|
||
| Keywords | `max_keywords` | (count of Keyword objects) | Total keywords allowed |
|
||
|
||
### Monthly Limits (Reset on Billing Cycle)
|
||
|
||
| Limit | Plan Field | Account Field | Description |
|
||
|-------|------------|---------------|-------------|
|
||
| Ahrefs Queries | `max_ahrefs_queries` | `usage_ahrefs_queries` | Live Ahrefs API queries per month |
|
||
|
||
### Removed Limits (Now Credit-Based)
|
||
|
||
The following limits were removed in v1.5.0 - credits handle these:
|
||
- ~~max_clusters~~ → Credits
|
||
- ~~max_content_ideas~~ → Credits
|
||
- ~~max_content_words~~ → Credits
|
||
- ~~max_images_basic~~ → Credits
|
||
- ~~max_images_premium~~ → Credits
|
||
- ~~max_image_prompts~~ → Credits
|
||
|
||
---
|
||
|
||
## Plan Tiers
|
||
|
||
| Plan | Credits/Month | Sites | Users | Keywords | Ahrefs Queries |
|
||
|------|---------------|-------|-------|----------|----------------|
|
||
| Free | 500 | 1 | 1 | 100 | 0 |
|
||
| Starter | 5,000 | 3 | 2 | 500 | 50 |
|
||
| Growth | 15,000 | 10 | 5 | 2,000 | 200 |
|
||
| Scale | 50,000 | Unlimited | 10 | 10,000 | 500 |
|
||
|
||
---
|
||
|
||
## Credit Operations
|
||
|
||
### Token-Based Operations (Text AI)
|
||
|
||
Credits calculated from actual token usage:
|
||
- `credits = ceil(total_tokens / tokens_per_credit)`
|
||
- `tokens_per_credit` defined per model in `AIModelConfig`
|
||
|
||
| Operation | Model Example | tokens_per_credit |
|
||
|-----------|---------------|-------------------|
|
||
| Keyword Clustering | gpt-4o-mini | 10,000 |
|
||
| Idea Generation | gpt-4o-mini | 10,000 |
|
||
| Content Generation | gpt-4o | 1,000 |
|
||
| Content Optimization | gpt-4o-mini | 10,000 |
|
||
|
||
### Fixed-Cost Operations (Image AI) - v1.7.1 Complete
|
||
|
||
Credits per image based on quality tier:
|
||
|
||
| Quality Tier | Model Example | Credits/Image |
|
||
|--------------|---------------|---------------|
|
||
| Basic | runware:97@1 | 1 |
|
||
| Quality | dall-e-3 | 5 |
|
||
| Premium | google:4@2 | 15 |
|
||
|
||
**Image Generation Credit Flow (v1.7.1):**
|
||
1. Pre-check: `CreditService.check_credits_for_image()` verifies sufficient credits
|
||
2. Generation: Images generated via `process_image_generation_queue` Celery task
|
||
3. Post-deduct: `CreditService.deduct_credits_for_image()` called per successful image
|
||
4. Logging: `CreditUsageLog` + `CreditTransaction` + `AITaskLog` entries created
|
||
5. Notifications: `NotificationService.notify_images_complete/failed()` called
|
||
|
||
### Free Operations
|
||
|
||
| Operation | Cost |
|
||
|-----------|------|
|
||
| Add keyword (manual) | 0 |
|
||
| Create content task | 0 |
|
||
| Edit content | 0 |
|
||
| Publish to WordPress | 0 |
|
||
| Sync from WordPress | 0 |
|
||
|
||
---
|
||
|
||
## Database Models
|
||
|
||
### Account (Credit Balance)
|
||
|
||
```python
|
||
class Account(models.Model):
|
||
credits = models.IntegerField(default=0) # Current balance
|
||
usage_ahrefs_queries = models.IntegerField(default=0) # Monthly Ahrefs usage
|
||
```
|
||
|
||
### Plan (Allocations)
|
||
|
||
```python
|
||
class Plan(models.Model):
|
||
included_credits = models.IntegerField(default=0) # Monthly allocation
|
||
max_sites = models.IntegerField(default=1)
|
||
max_users = models.IntegerField(default=1)
|
||
max_keywords = models.IntegerField(default=100)
|
||
max_ahrefs_queries = models.IntegerField(default=0) # Monthly Ahrefs limit
|
||
```
|
||
|
||
### CreditTransaction (Ledger)
|
||
|
||
```python
|
||
class CreditTransaction(models.Model):
|
||
account = models.ForeignKey(Account)
|
||
transaction_type = models.CharField() # purchase/subscription/refund/deduction
|
||
amount = models.DecimalField() # Positive (add) or negative (deduct)
|
||
balance_after = models.DecimalField()
|
||
description = models.CharField()
|
||
created_at = models.DateTimeField()
|
||
```
|
||
|
||
### CreditUsageLog (Analytics)
|
||
|
||
```python
|
||
class CreditUsageLog(models.Model):
|
||
account = models.ForeignKey(Account)
|
||
operation_type = models.CharField() # clustering/content_generation/image_generation
|
||
credits_used = models.DecimalField()
|
||
model_used = models.CharField()
|
||
tokens_input = models.IntegerField()
|
||
tokens_output = models.IntegerField()
|
||
created_at = models.DateTimeField()
|
||
```
|
||
|
||
---
|
||
|
||
## Business Logic
|
||
|
||
### CreditService
|
||
|
||
Location: `backend/igny8_core/business/billing/services/credit_service.py`
|
||
|
||
**Key Methods:**
|
||
|
||
```python
|
||
class CreditService:
|
||
@staticmethod
|
||
def check_credits(account, required_credits):
|
||
"""Check if sufficient credits available, raises InsufficientCreditsError if not"""
|
||
|
||
@staticmethod
|
||
def deduct_credits_for_operation(account, operation_type, model, tokens_in, tokens_out, metadata=None):
|
||
"""Deduct credits and log usage after AI operation"""
|
||
|
||
@staticmethod
|
||
def add_credits(account, amount, transaction_type, description):
|
||
"""Add credits (admin/purchase/subscription)"""
|
||
|
||
@staticmethod
|
||
def calculate_credits_from_tokens(operation_type, tokens_in, tokens_out, model=None):
|
||
"""Calculate credits based on token usage and model"""
|
||
```
|
||
|
||
### LimitService
|
||
|
||
Location: `backend/igny8_core/business/billing/services/limit_service.py`
|
||
|
||
**Key Methods:**
|
||
|
||
```python
|
||
class LimitService:
|
||
HARD_LIMIT_MAPPINGS = {
|
||
'sites': {...},
|
||
'users': {...},
|
||
'keywords': {...},
|
||
}
|
||
|
||
MONTHLY_LIMIT_MAPPINGS = {
|
||
'ahrefs_queries': {...},
|
||
}
|
||
|
||
@classmethod
|
||
def check_hard_limit(cls, account, limit_name, additional_count=1):
|
||
"""Check if adding items would exceed hard limit"""
|
||
|
||
@classmethod
|
||
def check_monthly_limit(cls, account, limit_name, additional_count=1):
|
||
"""Check if operation would exceed monthly limit"""
|
||
|
||
@classmethod
|
||
def increment_monthly_usage(cls, account, limit_name, count=1):
|
||
"""Increment monthly usage counter"""
|
||
```
|
||
|
||
### Usage in AI Operations
|
||
|
||
```python
|
||
# In content generation service
|
||
def generate_content(task, user):
|
||
account = task.site.account
|
||
|
||
# 1. Pre-check credits (estimated)
|
||
estimated_credits = 50 # Estimate for content generation
|
||
CreditService.check_credits(account, estimated_credits)
|
||
|
||
# 2. Execute AI function
|
||
content, usage = ai_engine.generate_content(task)
|
||
|
||
# 3. Deduct actual credits based on token usage
|
||
CreditService.deduct_credits_for_operation(
|
||
account=account,
|
||
operation_type='content_generation',
|
||
model=usage.model,
|
||
tokens_in=usage.input_tokens,
|
||
tokens_out=usage.output_tokens,
|
||
metadata={'content_id': content.id}
|
||
)
|
||
|
||
return content
|
||
```
|
||
|
||
---
|
||
|
||
## API Responses
|
||
|
||
### Successful Operation
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... },
|
||
"credits_used": 15,
|
||
"balance": 9985
|
||
}
|
||
```
|
||
|
||
### Insufficient Credits
|
||
|
||
```json
|
||
HTTP 402 Payment Required
|
||
|
||
{
|
||
"success": false,
|
||
"error": "Insufficient credits",
|
||
"code": "INSUFFICIENT_CREDITS",
|
||
"required": 50,
|
||
"available": 25
|
||
}
|
||
```
|
||
|
||
### Limit Exceeded
|
||
|
||
```json
|
||
HTTP 402 Payment Required
|
||
|
||
{
|
||
"success": false,
|
||
"error": "Keyword limit reached",
|
||
"code": "HARD_LIMIT_EXCEEDED",
|
||
"limit": "keywords",
|
||
"current": 500,
|
||
"max": 500
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Frontend Handling
|
||
|
||
### Credit Balance Display
|
||
|
||
- Header shows current credit balance
|
||
- Updates after each operation
|
||
- Warning at low balance (< 10%)
|
||
|
||
### Pre-Operation Check
|
||
|
||
```typescript
|
||
import { checkCreditsBeforeOperation } from '@/utils/creditCheck';
|
||
import { useInsufficientCreditsModal } from '@/components/billing/InsufficientCreditsModal';
|
||
|
||
function ContentGenerator() {
|
||
const { showModal } = useInsufficientCreditsModal();
|
||
|
||
const handleGenerate = async () => {
|
||
// Check credits before operation
|
||
const check = await checkCreditsBeforeOperation(50); // estimated cost
|
||
|
||
if (!check.hasEnoughCredits) {
|
||
showModal({
|
||
requiredCredits: check.requiredCredits,
|
||
availableCredits: check.availableCredits,
|
||
});
|
||
return;
|
||
}
|
||
|
||
// Proceed with generation
|
||
await generateContent();
|
||
};
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API Endpoints
|
||
|
||
### Credit Balance
|
||
|
||
```
|
||
GET /api/v1/billing/balance/
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"credits": 9500,
|
||
"plan_credits_per_month": 10000,
|
||
"credits_used_this_month": 500,
|
||
"credits_remaining": 9500
|
||
}
|
||
```
|
||
|
||
### Usage Limits
|
||
|
||
```
|
||
GET /api/v1/billing/usage/limits/
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"limits": {
|
||
"sites": { "current": 2, "limit": 5, "type": "hard" },
|
||
"users": { "current": 2, "limit": 3, "type": "hard" },
|
||
"keywords": { "current": 847, "limit": 1000, "type": "hard" },
|
||
"ahrefs_queries": { "current": 23, "limit": 50, "type": "monthly" }
|
||
},
|
||
"days_until_reset": 18
|
||
}
|
||
```
|
||
|
||
### Usage Analytics
|
||
|
||
```
|
||
GET /api/v1/account/usage/analytics/?days=30
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"period_days": 30,
|
||
"start_date": "2025-12-06",
|
||
"end_date": "2026-01-05",
|
||
"current_balance": 9500,
|
||
"total_usage": 500,
|
||
"total_purchases": 0,
|
||
"usage_by_type": [
|
||
{ "transaction_type": "content_generation", "total": -350, "count": 15 },
|
||
{ "transaction_type": "image_generation", "total": -100, "count": 20 },
|
||
{ "transaction_type": "clustering", "total": -50, "count": 10 }
|
||
],
|
||
"daily_usage": [
|
||
{ "date": "2026-01-05", "usage": 25, "purchases": 0, "net": -25 }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Credit Allocation
|
||
|
||
Credits are added to `Account.credits` when:
|
||
|
||
1. **Subscription Renewal** - `Plan.included_credits` added monthly
|
||
2. **Payment Approval** - Manual payments approved by admin
|
||
3. **Credit Purchase** - Credit packages bought by user
|
||
4. **Admin Adjustment** - Manual credit grants/adjustments
|
||
|
||
### Monthly Reset
|
||
|
||
Monthly limits (Ahrefs queries) reset on billing cycle:
|
||
|
||
```python
|
||
# In Account model
|
||
def reset_monthly_usage(self):
|
||
"""Reset monthly usage counters (called on billing cycle renewal)"""
|
||
self.usage_ahrefs_queries = 0
|
||
self.save(update_fields=['usage_ahrefs_queries'])
|
||
```
|
||
|
||
---
|
||
|
||
## Admin Operations
|
||
|
||
### Manual Credit Adjustment
|
||
|
||
Via Django Admin or API:
|
||
|
||
```python
|
||
from igny8_core.business.billing.services.credit_service import CreditService
|
||
|
||
# Add credits
|
||
CreditService.add_credits(
|
||
account=account,
|
||
amount=1000,
|
||
transaction_type='adjustment',
|
||
description='Customer support adjustment'
|
||
)
|
||
```
|
||
|
||
### Usage Audit
|
||
|
||
All credit changes logged in `CreditTransaction` with:
|
||
- Timestamp
|
||
- Transaction type
|
||
- Amount (positive or negative)
|
||
- Balance after transaction
|
||
- Description
|
||
|
||
All AI operations logged in `CreditUsageLog` with:
|
||
- Operation type
|
||
- Credits used
|
||
- Model used
|
||
- Token counts
|
||
- Related object metadata
|
||
|
||
---
|
||
|
||
## Image Generation Credit System (v1.7.1)
|
||
|
||
### Implementation Details
|
||
|
||
**Files:**
|
||
- `CreditService.check_credits_for_image()` - [credit_service.py:307-335](../backend/igny8_core/business/billing/services/credit_service.py#L307-L335)
|
||
- `process_image_generation_queue` credit check - [tasks.py:290-319](../backend/igny8_core/ai/tasks.py#L290-L319)
|
||
- `deduct_credits_for_image()` - [tasks.py:745-770](../backend/igny8_core/ai/tasks.py#L745-L770)
|
||
- AITaskLog logging - [tasks.py:838-875](../backend/igny8_core/ai/tasks.py#L838-L875)
|
||
- Notifications - [tasks.py:877-895](../backend/igny8_core/ai/tasks.py#L877-L895)
|
||
|
||
### Credit Flow for Image Generation
|
||
|
||
```
|
||
1. User triggers image generation
|
||
↓
|
||
2. CreditService.check_credits_for_image(account, model, num_images)
|
||
- Calculates: credits_per_image × num_images
|
||
- Raises InsufficientCreditsError if balance < required
|
||
↓
|
||
3. process_image_generation_queue() processes each image
|
||
↓
|
||
4. For each successful image:
|
||
CreditService.deduct_credits_for_image()
|
||
- Creates CreditUsageLog entry
|
||
- Creates CreditTransaction entry
|
||
- Updates account.credits balance
|
||
↓
|
||
5. After all images processed:
|
||
- AITaskLog entry created
|
||
- Notification created (success or failure)
|
||
```
|
||
|
||
### Logging Locations
|
||
|
||
| Table | What's Logged | When |
|
||
|-------|---------------|------|
|
||
| CreditTransaction | Credit deduction (financial ledger) | Per image |
|
||
| CreditUsageLog | Usage details (model, cost, credits) | Per image |
|
||
| AITaskLog | Task execution summary | After batch |
|
||
| Notification | User notification | After batch |
|
||
|
||
### Automation Compatibility
|
||
|
||
Image generation credits work identically for:
|
||
- Manual image generation (from UI)
|
||
- Automation Stage 6 (scheduled/manual automation runs)
|
||
|
||
Both call `process_image_generation_queue` which handles:
|
||
- Credit checking before generation
|
||
- Credit deduction after each successful image
|
||
- Proper logging to all tables
|