Skip to main content

Credits & billing

Every call draws down your org's credit balance. This page covers checking it, setting guardrails, and the read-only billing information available through the API.

Credit balance​

curl https://convostack.ai/api/credits/balance \
  -H "Authorization: Bearer cak_live_..."
{
  "balanceCredits": 5000,
  "monthlyCredits": 3000,
  "extraCredits": 2000,
  "planId": "starter",
  "lowCreditThreshold": 100,
  "isLow": false
}

balanceCredits is the spendable total; monthlyCredits (from your plan, resets each billing period) and extraCredits (from one-time top-ups or manual grants, never expire) are its breakdown — monthlyCredits is drawn down first.

# Transaction history
curl "https://convostack.ai/api/credits/transactions?limit=50" \
  -H "Authorization: Bearer cak_live_..."

Budgets and alerts​

A daily spend limit and a low-balance alert threshold — both soft guardrails, informational rather than call-blocking:

# Read the current budget + today's spend
curl https://convostack.ai/api/credits/budget \
  -H "Authorization: Bearer cak_live_..."

# Set a daily limit (pass null to remove it)
curl -X POST https://convostack.ai/api/credits/budget \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"dailyLimit": 500}'

# Set the low-balance alert threshold
curl -X PATCH https://convostack.ai/api/credits/threshold \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"threshold": 200}'
info

Credit deduction happens as calls complete, not up front — a budget here is a monitoring/alerting signal, not a hard cutoff enforced mid-call. If you're running high call volume, pair this with the rate limits on call-placing endpoints rather than relying on the budget alone.

Top-up packages​

curl https://convostack.ai/api/credits/packages \
  -H "Authorization: Bearer cak_live_..."

Lists the credit packages available to purchase. Actually buying one — like changing your subscription plan — happens through the dashboard's checkout flow, not the API: it's a Stripe payment, and needs a real logged-in billing contact rather than a headless script.

Plans, subscription, and invoices​

Read-only billing information is available via API; anything that changes money changing hands (subscribing, canceling, updating a payment method) is dashboard-only for the same reason as top-ups above.

# Available plans
curl https://convostack.ai/api/billing/plans \
  -H "Authorization: Bearer cak_live_..."

# Your org's current subscription
curl https://convostack.ai/api/billing/subscription \
  -H "Authorization: Bearer cak_live_..."

# Invoice history
curl https://convostack.ai/api/billing/invoices \
  -H "Authorization: Bearer cak_live_..."