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

# Credits

> Adding credit, and what a call actually costs.

Wixzel Voice is prepaid. You add credit, calls spend it per second, and you
cannot be billed for more than you put in.

## Adding credit

**Dashboard → Billing → Add credit.** Pick an amount, pay, and the balance moves
when the payment settles — usually within seconds.

<Note>
  Returning from checkout is not the same as the credit landing. Payment is
  confirmed by the provider calling us back, not by your browser coming home, so
  the dashboard waits for that rather than claiming success early.
</Note>

From the API, with `billing:write`:

```bash theme={null}
curl https://api.voice.wixzel.com/v1/billing/topups \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 25}'
```

The response carries a `checkout_url`. Send the customer there; the balance
moves on settlement. Minimum $5, maximum $10,000 per top-up — the floor stops
dust payments costing more in fees than they add, the ceiling is a fat-finger
guard rather than a limit on what you may spend.

`Idempotency-Key` is required here. See [Idempotency](/idempotency).

## What a call costs

Roughly **$0.04–$0.15 per minute**, depending on the engine — see
[Voice engines](/voice-engines) for the per-engine table. That covers speech
recognition, the model, speech synthesis, and a flat \$0.012 per connected
minute of orchestration.

It does **not** include telephony. You bring your own SIP trunk, so your carrier
bills you directly and we do not mark it up.

## Reading the balance

```bash theme={null}
curl https://api.voice.wixzel.com/v1/billing/balance \
  -H "Authorization: Bearer $WIXZEL_API_KEY"
```

```json theme={null}
{
  "object": "balance",
  "balance_micros": 24750000,
  "balance_display": "$24.75",
  "held_micros": 250000,
  "available_micros": 24500000
}
```

`held_micros` is credit reserved by calls in progress. `available_micros` is
what a new call can draw on.

### Micro-USD

Amounts are integer **micro-USD**: 1,000,000 = $1.00. Voice usage is billed per
second, per token and per character, and a charge of $0.000021 has no
float-dollar representation that agrees with the ledger. Responses carry a
`*_display` string alongside the integer so nothing has to do currency
arithmetic in JavaScript.

## Running out

Credit is reserved **before** a call is placed. An account that cannot fund the
first 15 seconds is refused with `402 insufficient_credits` at admission —
before a port is opened or a provider socket is created. You are not charged for
a call that never happened.

Mid-call, at roughly a minute of remaining runway, the agent speaks a warning to
your caller. At zero it speaks a closing line and hangs up. It does not drop the
line mid-sentence.

<Warning>
  A new account has a **\$0.50 credit limit**. This is not free trial credit — it
  is a grace margin so a call is never killed by a rounding race between the meter
  and the ledger. Do not budget against it.
</Warning>

## Tracing a charge

Every micro debited is explained by a usage row, so a bill is answerable without
asking support:

```bash theme={null}
curl "https://api.voice.wixzel.com/v1/usage/events?session_id=sip-4f2a" \
  -H "Authorization: Bearer $WIXZEL_API_KEY"
```

| Component      | Model                           | Quantity    | Cost         |
| -------------- | ------------------------------- | ----------- | ------------ |
| `stt`          | deepgram/nova-3                 | 187 s       | \$0.0336     |
| `llm`          | openrouter/gpt-4o-mini          | 8.2k tokens | \$0.0031     |
| `tts`          | elevenlabs/eleven\_turbo\_v2\_5 | 1.4k chars  | \$0.0980     |
| `platform_fee` | orchestration                   | 4 min       | \$0.0480     |
|                |                                 | **Total**   | **\$0.2714** |

Prices are frozen per call: a call is priced when it is admitted and finishes on
those rates, so a price change can never move a meter mid-conversation.

If our own process crashes mid-call you are charged for the seconds we can
prove, not the amount that was reserved.