---
title: Usage and cost accounting
description: Understand how Zorveus calculates virtual spend, wallet charges, provider costs, and cache-aware token usage.
---

Every inference request produces an immutable usage event recorded in your organization account.

---

## The three financial amounts

Inference requests generate three separate financial values. Each answers a different accounting question:

| Amount | Description | Applies to wallet mode | Applies to BYOK mode |
| :--- | :--- | :--- | :--- |
| `virtual_spend` | Reference-priced value of AI usage consumed against caps and credits | Yes | Yes |
| `sell_cost` | Amount debited from your Zorveus organization wallet | Yes | No ($0.00 provider charge, explicit platform fee may apply) |
| `provider_cost` | Upstream cost charged by the model provider | Yes (recorded for margin reporting) | Yes (recorded for fee calculation and cost reporting) |

Virtual spend uses identical reference pricing regardless of whether the call was funded by wallet or BYOK. Changing the funding source does not change how much product allowance the request consumes.

---

## Cache-aware token tracking

Zorveus tracks input tokens across cache categories:

- **Total input tokens (`input_tokens`)**: The normalized grand total of all input tokens, including normal input and cache categories.
- **Cache read tokens (`cache_read_input_tokens`)**: Tokens read from an active provider cache. These cost less than normal input tokens.
- **Cache creation tokens (`cache_creation_input_tokens`)**: Tokens written to cache with the default duration.
- **One-hour cache creation tokens (`cache_creation_1h_input_tokens`)**: Tokens written with a one-hour retention window.
- **Normal input tokens**: Uncached prompt tokens, calculated as total input minus cache reads and cache creations.

Settlement calculates `cache_savings` by comparing the cache-read cost against standard input rates. In BYOK mode, this value represents AI allowance saved on reference pricing, not provider bill discounts.

---

## Usage event dimensions

Each usage event captures full contextual and financial metadata:

| Dimension | Type | Description |
| :--- | :--- | :--- |
| `usage_event_id` | string | Unique identifier (`ue_...`) for the usage event. |
| `timestamp` | string | ISO 8601 timestamp of request completion. |
| `app_id` | string | Application identifier associated with the request. |
| `model` | string | Model name resolved for inference. |
| `provider` | string | Upstream provider executing the request (`openai`, `anthropic`, etc.). |
| `billing_mode` | string | `wallet` or `byok_external`. |
| `status` | string | `succeeded`, `partially_settled`, or `failed`. |
| `input_tokens` | integer | Total normalized input tokens. |
| `output_tokens` | integer | Output completion tokens. |
| `cache_read_input_tokens` | integer | Input tokens retrieved from provider prompt cache. |
| `cache_creation_input_tokens` | integer | Input tokens written with default cache duration. |
| `cache_creation_1h_input_tokens` | integer | Input tokens written with one-hour cache duration. |
| `virtual_spend` | decimal string | Reference-priced allowance consumed. |
| `sell_cost` | decimal string | Actual charge debited from the organization wallet. |
| `provider_cost` | decimal string | Upstream provider cost. |
| `uncovered_virtual_spend` | decimal string | Virtual spend exceeding allowance in track-only mode or overruns. |
| `unfunded_wallet_charge` | decimal string | Wallet charge that could not be debited due to wallet exhaustion. |
| `cache_savings` | decimal string | Reference-priced allowance saved by prompt caching. |
| `overrun_policy` | string | Active overrun policy: `limit_output`, `allow_overrun`, or `carry_overrun_forward`. |
| `product_end_user_id` | string | Internal Zorveus identifier for the attributed product user. |
| `external_user_id` | string | Customer lookup ID from your application. |

All financial amounts are represented as decimal strings with high fractional precision. SDKs and custom integrations should parse them with a decimal library rather than binary floating point.