> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca-klavest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing & Tokens

> Understand ORCA's token-based pricing model, plan tiers, AI tier selection, and usage tracking.

## 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:

```bash theme={null}
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

```bash theme={null}
curl https://api.orca-klavest.app/api/v1/billing/token-status \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "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.

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

Response:

```json theme={null}
{
  "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:

```bash theme={null}
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:

1. The system checks your available balance.
2. If sufficient tokens are available, they are deducted atomically using a database lock.
3. If the operation fails (e.g. queue unavailable), tokens are refunded automatically.
4. 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               |