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.

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:

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.