> ## 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. Packs are priced in US dollars or naira, and you pay in the currency of the pack you choose. Naira prices follow the day's exchange rate, so list the packs again before showing a price. If no rate is available, only dollar packs are listed. 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.