Billing & Tokens

Token-based pricing

ORCA uses a token-based billing model. Every AI-powered operation consumes tokens from your monthly allowance. Tokens refill at the start of each billing cycle.

Plans

	Free	Pro	Enterprise
Price	Free	EUR 99/month	EUR 499/month
Monthly tokens	50	5,000	25,000
Overage	Not available	EUR 0.03/token	EUR 0.025/token
Overage cap	—	2x allowance (10,000)	2x allowance (50,000)
AI tier	Basic only	Basic or Advanced	Basic or Advanced
Report scheduling	—	Weekly, monthly, quarterly	Weekly, monthly, quarterly
Team members	1	Unlimited	Unlimited

Token costs per operation

Each operation has a different token cost depending on the selected AI tier:

Operation	Basic (Gemini)	Advanced (Sonnet)
Classification (per column)	1	3
Chat — simple query	1	3
Chat — complex query	2	5
Chat — action query	3	8
Report generation	5	10
AI Readiness scoring	Free	Free

AI Readiness scoring is always free — it is a core feature of the platform.

AI tiers

ORCA offers two AI tiers that determine which model processes your data:

	Basic	Advanced
Model	Gemini 2.5 Flash	Claude Sonnet 4
Best for	High-volume classification, standard analysis	Complex queries, nuanced classification
Token cost	Lower	2-3x higher
Speed	Faster	Slightly slower
Availability	All plans	Pro and Enterprise only

Switch tiers from Settings > Billing or via the API:

curl -X PATCH https://api.orca-klavest.app/api/v1/billing/ai-tier \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ai_tier": "advanced"}'

Switching tiers requires the admin role. The change takes effect immediately for all subsequent operations.

Checking your balance

From the UI

Navigate to Billing in the sidebar to see your current token balance, monthly allowance, usage breakdown, and billing cycle dates.

From the API

curl https://api.orca-klavest.app/api/v1/billing/token-status \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": {
    "balance": 4250,
    "allowance": 5000,
    "used": 750,
    "plan": "pro",
    "ai_tier": "basic",
    "cycle_start": "2026-03-01T00:00:00Z",
    "cycle_end": "2026-03-31T23:59:59Z"
  }
}

Token ledger

Every token transaction is recorded in an append-only ledger. The ledger provides a complete audit trail of token consumption and refills.

curl "https://api.orca-klavest.app/api/v1/billing/token-ledger?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": {
    "total": 142,
    "entries": [
      {
        "id": "e1f2a3b4-...",
        "delta": -2,
        "balance_after": 4248,
        "operation": "chat_complex",
        "ai_tier": "basic",
        "metadata": {"conversation_id": "..."},
        "created_at": "2026-03-31T14:30:00Z"
      }
    ]
  }
}

Filter by operation type using the operation query parameter:

curl "https://api.orca-klavest.app/api/v1/billing/token-ledger?operation=classify" \
  -H "Authorization: Bearer $TOKEN"

How tokens are deducted

Tokens are deducted at the time the operation is initiated:

The system checks your available balance.
If sufficient tokens are available, they are deducted atomically using a database lock.
If the operation fails (e.g. queue unavailable), tokens are refunded automatically.
If your balance is insufficient, the operation returns a 402 Payment Required response.

Overage tokens are charged at the end of the billing cycle for Pro and Enterprise plans. Free plan users cannot exceed their monthly allowance.

API reference

Method	Endpoint	Description
`GET`	`/api/v1/billing/token-status`	Current token balance, allowance, plan, and cycle
`PATCH`	`/api/v1/billing/ai-tier`	Switch AI tier (admin only)
`GET`	`/api/v1/billing/token-ledger`	Paginated token transaction history

Getting started

Features

Administration

Integrations

Security & compliance

Developer Tools

Methodology

Token-based pricing

Plans

Token costs per operation

AI tiers

Checking your balance

From the UI

From the API

Token ledger

How tokens are deducted

API reference

​Token-based pricing

​Plans

​Token costs per operation

​AI tiers

​Checking your balance

​From the UI

​From the API

​Token ledger

​How tokens are deducted

​API reference

Token-based pricing

Plans

Token costs per operation

AI tiers

Checking your balance

From the UI

From the API

Token ledger

How tokens are deducted

API reference