Billing, budgets and idempotency

Everything is in USD. Usage, credit, budgets, the ledger and invoices are in the dashboard under Core > Credit and usage (/app/core/credits).

What a request costs

oryvox.cost is the model cost of the request at the provider's list price (versioned, see below). What you are charged:

Request	Charge
On ORYVOX provider capacity	`cost × (1 + markup)`; the markup is 10%
On your own provider key (BYOK)	No percentage: the provider bills you for the tokens; your Core plan is the price
Failed (any non-200 answer)	Free
Answered from the cache	Free
Test mode (`ory_test_` keys)	Free (simulated), and not counted toward the plan

Plans

Usage is paid in USD from credit; the plan (EUR a month) covers the platform:

Plan	Price	Includes
Free	€0	10,000 requests a month (beyond: `402 plan_limit`)
Pro	€49 / month	Unlimited requests
Business	€199 / month	Unlimited requests, SSO, the audit log, Zero retention

Failed and refused requests and test mode do not count toward the allowance. Plans are chosen in the dashboard (Core → Credit and usage), with a 14-day trial of Pro and Business.

The charge of each request is booked once, by request id, so a replayed idempotent request is never charged twice.

Credit

A company is prepaid (the default) or postpaid:

Prepaid. Top up credit in the dashboard. Before a request runs, ORYVOX reserves an estimate (twice the expected charge, at least $0.002) from the available balance and settles the exact charge afterwards. If the available credit does not cover the reservation the request fails with 402 insufficient_credits (InsufficientCreditsError in the SDKs, a subclass of BudgetExceededError). BYOK requests are not reserved (nothing is charged).
Postpaid (set up by ORYVOX): requests run up to the agreed credit limit, then fail with 402 insufficient_credits; usage is invoiced monthly.

Webhooks: credits.low when the balance falls below your low-balance threshold, and credits.exhausted when it reaches zero (each once per crossing).

Plans

The company's ORYVOX Core plan (Free, Pro or Business) sets features and the monthly request allowance (Free: 10,000 requests). Usage is paid from credit separately. When a live key's company has used its allowance, requests fail with 402 plan_limit until the next month or an upgrade.

Budgets

Spend limits are in charged USD (what you pay, including the markup):

Limit	Where
Project, per day and per month	Project settings
Key, per day	Key settings
Per request	Project `max_request_cost`, or `max_cost` in the request (USD, model cost): models that could cost more are not used
Per agent workflow	`oryvox.workflow_budget` (Agents)

The project's budget action decides what happens:

`budget_action`	Behaviour
`block` (default)	At 100% of a project budget requests fail with `402 budget_exceeded`.
`downgrade`	From the warning level (`budget_warn_at`, default 80%) requests are routed in `economy` mode and each is capped at what is left; at 100% they fail with `402 budget_exceeded`.
`warn`	Project budgets never stop requests; only the events fire.

budget.warning fires at the warning level and budget.exceeded at 100%, once per period each. Key daily budgets always block. 402 errors are never retried by the SDKs.

Idempotency

Send an Idempotency-Key header (max 255 characters) on POST /chat/completions, /responses or /embeddings:

Situation	Result
Same key, same body, within 24 hours, first request finished	The stored response is returned again with `Idempotent-Replayed: true`; no model is called and nothing is charged again.
Same key, same body, first request still running	`409 conflict` (`ORYX_4091`): retry shortly.
Same key, different body (or another endpoint)	`422 idempotency_mismatch`.
First result was 5xx, 401, 403 or 429	Nothing is stored: a retry with the same key runs again.
First request was streamed, or the project uses Zero retention	Its result is not kept: a repeat answers `409 conflict` (`ORYX_4092`, "already processed").

Other results (200, and 4xx such as 400 or 402) are replayed as they were. Stored results are encrypted and kept 24 hours; keys are per company.

curl https://api.oryvox.ai/v1/responses \
  -H "Authorization: Bearer $ORYVOX_API_KEY" \
  -H "Idempotency-Key: checkout-7f3a-summary" \
  -H "Content-Type: application/json" \
  -d '{"model": "oryvox-auto", "input": "..."}'

The SDKs generate one key per logical POST whenever retries are enabled and reuse it for every retry. Pass your own (idempotencyKey / idempotency_key) to make a call idempotent across processes. A replayed result has idempotentReplayed === true (Node) / idempotent_replayed == True (Python).

Pricing versions

Model prices are versioned. Each request records the price version it was priced at, so later price changes never alter past costs. Current list prices are in GET /models (oryvox.input_price / output_price, USD per million tokens).

Savings

oryvox.saved is what the request would have cost without ORYVOX minus what it did cost (model cost). The baseline is the project's reference model for the original, unoptimised token count; without one, the platform reference model (anthropic/claude-sonnet-5.5). Savings come from routing, cache hits, token optimisation and provider prompt caching; the request log breaks them down per source.

Invoices

Invoices are created monthly per company from the usage meter, per project and model (invoice.created, invoice.paid, invoice.failed webhooks). Prepaid statements show usage already paid from credit; postpaid invoices show the amount due. Both are in the dashboard, with a CSV export of usage.