Credit System — ArrowFlow Docs

ArrowFlow uses a token-based credit model where credits are consumed each time an AI model is invoked. Credits abstract away the underlying token cost of different models, providing a simple usage metric.

Core Concept

1 credit = 1,000 tokens on the nano baseline

When you use a more expensive model, credits are consumed faster via multipliers. When you use the cheapest model, 1 credit = 1,000 tokens exactly.

Model Multipliers

Model	Multiplier	Effective Cost
gpt-5.4-nano	1×	1 credit per 1,000 tokens
gpt-5.4-mini	3×	3 credits per 1,000 tokens
claude-opus-4-6	10×	10 credits per 1,000 tokens

Credits are fractional — a 500-token nano call costs 0.5 credits. The minimum charge per call is 0.1 credits.

Subscription Tiers

Tier	Price	Credits	Renewal	Max Diagrams
Free	$0	5,000	One-time (no renewal)	3
Starter	$4/mo	7,000	Monthly	10
Pro	$12/mo	25,000	Monthly	Unlimited
Enterprise	$29/mo	60,000	Monthly	Unlimited

Free Tier

New users receive a one-time 5,000-credit welcome grant. Once exhausted, credits are not renewed until the user upgrades. Limited to 3 diagrams.

Paid Tiers

Credits reset to the tier's monthly allocation on the renewal date. Unused credits do not roll over.

Credit Pack (On-Demand)

For users who need extra credits without changing tiers:

3,000 credits for $2 (one-time purchase)
Purchased credits are added on top of the monthly balance
Purchased credits persist across renewal cycles until consumed

BYOK (Bring Your Own Key)

Users who provide their own API keys for AI models bypass credit consumption entirely. Their model calls go directly to the provider at the user's own cost. BYOK users still consume credits for ArrowFlow-hosted model calls.

Monthly Renewal

reset_date is set 30 days from the subscription start
On renewal, credits_balance is set to credits_monthly (not added to remaining)
Purchased credits (credits_purchased) are tracked separately and persist

Credit Events (Audit Log)

Every credit change is logged as a credit_event document in CosmosDB:

{
  "id": "evt_1714600000000_abc123",
  "userId": "user_...",
  "type": "credit_event",
  "timestamp": "2026-05-02T00:00:00Z",
  "amount": -2.5,
  "reason": "agent_usage",
  "model": "gpt-5.4-nano",
  "balance_after": 4997.5
}

Reasons include:

initial_grant — first-time credit allocation
plan_reset — monthly renewal or admin tier reset
agent_usage — AI model invocation
admin_adjustment — manual operator change
credit_pack_purchase — Stripe credit pack
courtesy_grant — support/compensation

Azure Cost Basis

Credits are priced against Azure's blended token rate:

Azure cost per credit: $0.000295 (based on GPT-5-nano, 30% input / 70% output blend)
Target margins: Starter ~48%, Pro ~39%, Enterprise ~39%
Credit pack margin: ~56%

Data Model

Credits are stored in the CosmosDB users container (partition key: /userId) as a plan document:

{
  "id": "plan",
  "userId": "user_...",
  "type": "plan",
  "tier": "pro",
  "credits_balance": 24500.5,
  "credits_monthly": 25000,
  "credits_purchased": 3000,
  "reset_date": "2026-06-01T00:00:00Z"
}