# Billing, Balance & AI credits

Each workspace has one plan and one Balance. The plan decides what you can create and what is included each month; the Balance pays for anything beyond. Money your customers pay you through Payments is Earnings, held per project — it never pays Harakumo and the Balance never pays you.

## Plans

Limits & scaling lists every count. Plans limit how many things you create; data size, storage bytes and bandwidth have no plan quota yet.

Free limits are per person, across all your free workspaces. Every paid workspace has its own limits. Hobby is free: static sites, functions, databases, storage, sign-in, email and payments within its counts. Server apps are on Pro and up, videos and live channels on Pro and up, and AI on Hobby is paid from the Balance.

Every price is in US dollars and does not include taxes such as sales tax, VAT or GST.

|  | Hobby | Pro | Enterprise |
| --- | --- | --- | --- |
| Price (per workspace) | Free | $20 a month | $500 a month |
| AI usage | Pay as you go from your balance | $10 a month included | $100 a month included |
| Emails (rolling 30 days) | 100 | 5,000 | 100,000 |

## Changing plan

- Only the owner changes the plan, from Dashboard → Billing or `POST /api/billing { plan }`.
- Upgrading charges the prorated difference now; the plan changes once that payment succeeds.
- Downgrading between paid plans starts at the next renewal. Moving to Hobby ends the subscription at the end of the period; `POST /api/billing { action: "resume" }` (Keep plan) withdraws a pending cancel or downgrade.
- Nothing is deleted on a downgrade; creating more than the new plan allows is refused.
- Hobby does not include server apps, videos or live channels: new deployments of a server app, new video uploads and going live are refused there, and AI is paid from the balance.
- A missed subscription payment keeps the plan while the processor retries, with included AI paused (AI is then paid from the Balance); an unpaid subscription drops to Hobby limits until it is paid.
- If checkout says a plan's price is being updated, nothing was charged; try again later.

## Included AI usage

- $10 on pro, $100 on enterprise each month. Hobby includes none: every AI request there is paid from the Balance, pay as you go, and vendor models need the owner's verified email.
- It resets on the 1st at 00:00 UTC and does not carry over. It is used first; then the Balance pays.
- AI is priced at each model's per-token price: the model maker's list price, plus up to 5% on third-party models to cover buying that usage (edge models never carry it). `GET /api/ai/chat` lists the exact price of every model. Every answer reports its exact cost.
- Billing → Balance breaks this month's AI usage down by model: requests, tokens in and out, and spend for each, from the records the charges were made from — chat, embeddings, memory and vectors alike (`ai_usage.by_model` in `GET /api/billing/balance`). Charges recorded without a model, from before per-model recording and from agent runs, are one Unattributed row; each agent run shows its own model and cost.

## Domains

Domains are not part of any plan. Every purchase, renewal and transfer is paid from the Balance at the price shown first (or the card, when a signed-in owner asks), and there is no limit on how many you buy. Connecting a domain you already own is free, up to the plan's custom-domain limit.

## The Balance

- Prepaid dollars the owner loads from Dashboard → Billing → Balance: $10 to $1,000 at a time, with the card on file or through checkout (which saves the card).
- It never expires and is not refundable. Deleting a workspace gives it up only after you confirm.
- It pays for AI beyond the included amount and for every domain purchase, renewal and transfer.
- A card is charged only when you choose: an owner paying with the card for one purchase (`payWithCard: true`), auto-reload, or domain renewal card backup the owner turned on.
- Every movement — funds added, AI usage, domains, refunds, plan invoices — is a transaction on the Billing page, with receipts for card charges.

## Spending limit and alerts

- Set a monthly spending limit ($1 to $100,000; 0 for none) in Billing → Limits & alerts or `PATCH /api/billing/limits { spendLimitCents }` (owner). It covers AI beyond the included amount plus domain purchases from the Balance or the card. Past it, requests answer 402 `spend_limit_reached`.
- Alerts (`alertLevels`, default 50, 80 and 100 percent) email the owner once per level per month, for the included AI amount and for the limit.
- Auto-reload charges the card a chosen amount when available AI credit drops below a threshold, at most 10 times a month. It fires only for requests from a signed-in person unless the owner sets `autoReloadForKeys: true`.

**curl (owner session)**

```bash
PATCH /api/billing/limits
{ "spendLimitCents": 5000, "alertLevels": [50, 80, 100], "autoReloadForKeys": false }
```

## Seller earnings

Payments you take are Earnings on the project: each sale less the 3.9% + 30¢ fee, held 7 days, then withdrawn by the workspace owner. See Payments.

## When things reset

| What | Clock |
| --- | --- |
| Included AI usage | The 1st of each month, 00:00 UTC |
| Spending limit, alerts, auto-reload count | Calendar month (UTC) |
| Email quota | Rolling 30 days |
| Subscription | Monthly from the day you subscribed |
| Domain renewals | Each domain's own expiry date |
| Earnings hold | 7 days after each payment |

## Who can see and change billing

- Admins and owners can see billing; only the owner can change the plan, cards, Balance, auto-reload and limits.
- API keys see the AI credit summary in `GET /api/usage` (`aiCredits`) and cannot read or change billing. An owner's AI connector can read the Balance.

## Reference

**SDK**

```js
const { aiCredits } = await hk.usage.get();
// { balance_usd, available_usd, included_usd, included_used_usd, included_remaining_usd, resets_on, buy_url, auto_reload }
// Billing changes are made by the owner in the dashboard (an API key acts as developer).
```

**CLI**

```bash
harakumo balance      # Balance, included AI this month, what is available
harakumo usage
```

**REST**

```http
GET   /api/usage                       → aiCredits { balance_usd, available_usd, included_usd, included_remaining_usd, resets_on, buy_url }
GET   /api/billing                     # plan, subscription state, limits and usage (admin+)
POST  /api/billing                     { "plan": "hobby"|"pro"|"enterprise" } | { "action": "resume" }   (owner)
GET   /api/billing/balance             # balance, credits, transactions, this month's AI usage by model (admin+)
POST  /api/billing/balance             { "cents": 2500 }   Idempotency-Key: <unique>   (owner; card on file)
POST  /api/billing/balance/checkout    { "cents": 2500 }   → { url }
PATCH /api/billing/balance             { "autoReloadCents": 1000, "autoReloadBelowCents": 200 }
GET   /api/billing/limits · PATCH { "spendLimitCents"?, "alertLevels"?, "autoReloadForKeys"? }   (owner)
```