Credits & billing
How CocoboxAI credits are priced, consumed, refunded, and visible in your invoices.
A credit is the unit Cocobox bills for AI usage when you’re not using BYOK.
What costs credits
| Action | Cost |
|---|---|
| AI request via the editor (NL→SQL, fix, explain) | Per-model rate from CocoboxAI models |
| Chat turn | Per-model rate |
API request to /v1/chat/completions or /v1/messages | Per-model rate |
MCP tool call (sql_run, etc.) | Free — uses the API key’s request budget instead |
| Schema introspection, query execution, exports | Free |
Failed requests (4xx/5xx) are not charged. Aborted requests (you cancel mid-stream) are charged at half rate based on tokens delivered.
Where credits come from
- Plan inclusion — every paid plan includes a monthly credit allotment.
- Top-ups — buy more any time. Top-ups don’t expire.
- Promotional — onboarding credits, referral bonuses. These expire as noted.
Order of consumption: promotional → plan → top-ups. So plan credits never expire while you have promotional balance.
Watching usage
Settings → Billing → Usage:
- Daily and monthly credit burn.
- Breakdown by model alias and by user.
- Forecast: “at this rate, you’ll exhaust your plan by …”.
- Alert thresholds: email at 50%, 80%, 100%.
Per-API-key budgets
When you create an API key, you can set a request_budget — a credit cap. Once hit, the key starts returning 429 budget_exceeded until you raise the cap or the calendar month rolls over. Useful for handing a key to an experiment without risking your monthly allotment.
Invoices
Invoices are generated on the 1st of each month for the previous month. Includes:
- Plan fee.
- Top-ups purchased in-period.
- Detailed credit ledger (PDF appendix).
Download from Settings → Billing → Invoices, or have them auto-mailed to your finance team.
Refunds
We refund credits for:
- Verified outages on Cocobox’s side that affected your workspace.
- Documented model-quality regressions during the first 24 hours after we change an alias’s underlying model.
Email billing@cocobox.io within 30 days.