Claude API Billing FAQ: Pre-Holds, Refunds, Trial Credit, and Usage Logs

If you're calling Claude through an API gateway, the question that comes up more than anything else isn't "which models do you support" — it's "how exactly does this charge get calculated." Why does the pre-hold amount differ from the final bill? What happens to a failed call? Is trial credit automatic or do you have to ask for it? Can usage logs be exported for reconciliation?

This FAQ walks through the actual billing flow, one mechanism at a time, and every answer is something you can verify yourself. It intentionally skips hard price numbers — pricing changes in real time, so the source of truth is always the live table at /pricing.

The three stages of a billed call: pre-hold → settle → refund

What happens the instant a request goes out?

Billing on a single call isn't "charge once when it's done" — it's a three-step process:

1. Pre-hold. The moment a request is sent — before the result comes back — the gateway reserves an estimated amount against your balance. This happens before the request even reaches the upstream model.
2. Settle. Once the upstream response lands, the gateway recalculates the real cost from the actual token usage the provider returned, and that real cost replaces the pre-hold. You're never billed the estimate — only the true amount, adjusted up or down.
3. Refund. If the call ultimately fails (a 5xx from upstream, for example), the pre-hold is released back to your balance automatically. No charge.

This three-stage flow is the core of how billing works, and it's why your bill always lines up with what you actually got back — you're charged for real token usage, not for the act of sending a request.

Why doesn't the pre-hold match the final charge?

At pre-hold time, the gateway has no idea yet how many tokens the model is going to generate, so it reserves against an estimate — mainly to keep concurrent requests from over-drawing your balance. Once the real completion token count is known, the gateway recalculates from that. The pre-hold is just a placeholder in the accounting, never the final number. If you see a request sitting in a "pending" state in the Playground or usage log, refresh in a few seconds and it'll show the settled amount.

Does one request ever get charged twice?

No. Every request maps to exactly one final charge (or one refund) — the pre-hold is a bookkeeping step, not a separate line item.

When does a call get refunded automatically?

Do I pay for upstream errors?

No. If a call fails because of an upstream outage — after the gateway has already retried across channels — you're not billed for it. The pre-hold reverses automatically; there's no ticket to file, no form to fill out. This applies uniformly across every model the gateway routes to, regardless of which upstream served it.

Does a 429 count as a billable failure?

No charge is generated by a rate-limit response, because there's no billable result to begin with. A 429 usually means you're sending requests too densely in a short window — back off exponentially and retry rather than hammering it again immediately.

What if I mess up my own request, like typo a model id?

You're not charged. Request-level errors — a 404 for an unknown model, a 401 for an invalid key — get rejected before the call ever reaches the billing/settlement stage.

Here's a quick-reference table of the common error codes and what to do about each:

| Status | Cause | What to do | |---|---|---| | 401 | API key missing or invalid | Check the Authorization header and confirm the key hasn't been revoked | | 402 / 403 | Insufficient balance | Top up from the Billing page in your console | | 404 | Model id doesn't exist, or isn't in this key's allowlist | Cross-check the real id in the /models catalog | | 429 | Rate limited | Retry with exponential backoff | | 5xx | Upstream channel failure | The gateway retries automatically across channels; if it still fails, you're not billed and the pre-hold is refunded |

How trial credit works

Do I need to add a card to get trial credit?

No. New accounts get trial credit automatically on signup, credited straight to your balance — no payment method required, no application, no support ticket.

Which models can I use trial credit on?

Trial credit lands in the same balance as paid top-ups — there's no separate bucket and no restriction to a subset of models. Anything in the catalog is callable with it.

Does trial credit expire or get clawed back?

Account balance has no expiration, and trial credit is no exception — once it's granted, it behaves like any other balance and doesn't get zeroed out from inactivity. The exact amount granted matches what's shown on the signup page at the time — the display logic and the grant logic are the same code path, so there's no gap between what's advertised and what actually lands in your account.

Where to find usage data, and how CSV export works

Where do I see what each call actually cost?

The Usage page in your console logs every call with the model used, prompt/completion token counts, latency, whether it was streamed, and the exact amount charged. Entries are also typed — Call, Top-up, Refund, Error, and so on — so you can filter by type instead of eyeballing a raw feed.

How precise is the per-call cost?

Down to six decimal places. That precision exists so that even very small individual calls reconcile cleanly in the log instead of getting rounded away.

Can I export billing data to reconcile against?

Yes — the Usage page supports filtering by date range and exporting to CSV, capped at 1,000 rows per export. For high-volume accounts, export in batches by time window rather than trying to pull everything at once.

How do I get token usage in code, instead of checking the console?

For streaming requests, add stream_options.include_usage to the payload — the final chunk will carry the real token counts, which is the exact number billing is based on. Here's what a typical (non-streaming) request looks like, with {GATEWAY_BASE_URL} swapped in for your deployment's actual gateway address:

curl {GATEWAY_BASE_URL}/chat/completions \
  -H "Authorization: Bearer $APIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

This is a standard OpenAI-compatible request — just put the real catalog id in model, no separate request format for the Claude family. Check /models for the current list of available ids.

The short version

Claude billing on the gateway comes down to three sentences: estimate and pre-hold, settle on real usage, refund automatically on failure. There's no minimum spend and no subscription — one balance covers every model in the catalog, and detailed usage logs plus CSV export mean you can verify every charge yourself instead of taking it on faith.

If you haven't tried it yet, signing up grants trial credit automatically — no card required — so you can run a few real calls and see whether the bill matches what you expected before committing to anything. For live per-token pricing, check /pricing. Ready to wire it in? Start at /sign-up.