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

# Billing

> Buy prepaid credits, refill automatically and track your balance.

Every call spends credits from your organization's prepaid balance. See your prices with `GET /v1/billing/rates` and your balance with `GET /v1/billing/balance`.

## Buy credits

List the available packs, then start a top-up with a pack ID. Buying credits needs a login session, so a leaked API key can't charge your card.

```bash theme={null}
curl -b cookies.txt -X POST https://api.vocalistic.ai/v1/billing/top-ups \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a-unique-value' \
  -d '{"pack_id": "YOUR_PACK_ID"}'
```

Open the `checkout_url` in the response to pay. Credits arrive as soon as the payment clears. Sending the same `Idempotency-Key` again returns the same top-up rather than starting another.

Use `POST /v1/billing/portal` to get a link to your invoices and saved card.

## Refill automatically

Once you've paid with a card, you can have us buy a pack whenever your available credits fall below a threshold:

```bash theme={null}
curl -b cookies.txt -X PUT https://api.vocalistic.ai/v1/billing/auto-refill \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true, "threshold": 50, "pack_id": "YOUR_PACK_ID"}'
```

We check about once a minute, and we won't refill more than once every 10 minutes, so a fast-spending organization can still run out. If the card fails, we email your owners and billing members. After three failures in a row, auto-refill turns off.

## Low-balance alerts

We email your owners and billing members when your available credits fall below a threshold, 10 by default. Change it with `PUT /v1/billing/alerts`, or set it to 0 to turn alerts off.

## Refunds and disputes

A refund or a card dispute removes the matching share of the credits you bought. If that takes your balance below zero, your organization is suspended until you top up. API calls return `403 organization_suspended` until then, but you can still buy credits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.