Credits System

CutX uses a credit-based billing system. Every AI generation costs credits, deducted atomically when a job is created.

Credit Costs

Job Type	Credits	Underlying Cost	Model
copy	1	Free (Workers AI)	Llama 3.1 70B
static_ad	3	~$0.04/image	Flux 1.1 Pro
tts	2	~$0.045/30s	Minimax Speech
ugc_video	40	~$4.50/30s	OmniHuman
i2v	10	~$0.50–1.00/clip	Wan 2.2
reframe	20	~$2.50/30s	Luma
scrape	0	Free	Built-in

How Deductions Work

Credits are deducted before the job runs — not after:

1. User submits generation request
2. System checks credit balance
3. If sufficient → atomically deduct credits + create job
4. If insufficient → return 402 (Payment Required)
5. Job enters queue for processing

The deduction is recorded as a credit_transaction with:

• type: "deduction"
• reference_id: the job ID
• balance_after: new balance after deduction

Atomic Guarantees

The deductCredits() function uses a conditional update:

UPDATE credit_balances
SET balance = balance - $cost,
    lifetime_used = lifetime_used + $cost
WHERE user_id = $userId AND balance >= $cost

If the balance is too low, zero rows are affected and the request is rejected. This prevents race conditions from concurrent requests.

Refunds

Credits are refunded automatically when a job fails:

Job fails → markJobFailed() → refundCredits()

Refunds create a transaction with:

• type: "refund"
• reference_id: the job ID
• description: reason for the refund

Refunds restore the exact number of credits that were deducted. Scrape jobs (0 credits) skip the refund step.

Adding Credits

Credits enter user accounts through four channels:

Type	Description
purchase	One-time credit pack via Stripe Checkout
subscription	Monthly allocation from an active plan
bonus	Admin-granted credits (promotional, support)
free_tier	25 credits on account creation (automatic)

Credit Packs

Pack	Credits	Price
Starter	50	$4.99
Creator	150	$12.99
Pro	500	$39.99
Studio	1500	$99.99

Subscription Tiers

Tier	Monthly Credits	Price	Ad Spend Fee
Free	25 (one-time)	$0	6%
Starter	100/mo	$9.99/mo	6%
Pro	500/mo	$29.99/mo	5%
Agency	2000/mo	$99.99/mo	4%

Subscription credits are added on each billing cycle. Unused credits carry over — they never expire.

Balance Tracking

Each user has a credit_balances row with:

Field	Description
balance	Current spendable credits
lifetime_purchased	Total credits ever added
lifetime_used	Total credits ever deducted

A trigger automatically creates this row with 25 free credits when a new user signs up.

Transaction History

Every credit movement is logged in credit_transactions:

{
  "id": "uuid",
  "user_id": "uuid",
  "amount": -3,
  "type": "deduction",
  "description": "static_ad generation",
  "reference_id": "job-uuid",
  "balance_after": 47,
  "created_at": "2026-03-09T..."
}

This provides a complete audit trail for debugging and support.