# Prepaid credit

How you add credit to the account, see what is left, get unspent credit back, and what happens when it runs out. What credit pays for is on [Pricing](/pricing).

## Before you start

Only the owner or an admin adds credit, and the account needs its plan. An agent cannot top up.

## Add credit

```text
Top up my STACK credit with 50 dollars.
```

The client calls `stack_start_wallet_top_up` and returns a link to Stripe's checkout page. You pay there. The credit is added when Stripe confirms the payment. You can also top up in the Console, or over the API:

```bash
curl -X POST https://api.getstack.run/v1/billing/topup \
  -H "Authorization: Bearer <access token>" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000 }'
# { "checkout_url": "...", "session_id": "..." }
```

- The smallest top-up is $5.
- The card fee is its own line on the checkout page. The credit added is the amount you chose.
- There is no SDK method or terminal command for a top-up.

## See what is left

`stack_usage` returns the balance with the month's use. From the terminal, `usage` prints it. Over the API: `GET /v1/billing/balance` and `GET /v1/billing/transactions`.

## Get unspent credit back

```bash
curl -X POST https://api.getstack.run/v1/billing/refund/<transaction-id> \
  -H "Authorization: Bearer <access token>"
```

- A refund returns the unspent part of one top-up to the card that paid it.
- It needs your approval in a browser. The first call answers with the approval link.
- The card fee is not returned. Credit that STACK gave you is spent first and is never refunded.
- It works even after the plan has ended.

## When credit runs out

- Work inside what the plan includes keeps running.
- Anything that would be charged is refused with 402 INSUFFICIENT_BALANCE until you top up.
- A local phone number that waits for its first top-up is issued once a top-up lands.

If a top-up is disputed with the card issuer, paid actions are refused with `402 SPEND_FROZEN` until the dispute is settled. Work inside what the plan includes still runs.

## Limit one agent

Credit is shared by all of your agents. With controls on, you can give one agent a monthly budget, when its account is opened (`monthly_budget_cents`) or later. Past it, that agent is refused with `402 AGENT_BUDGET_EXCEEDED` until the next month.

```typescript
await stack.accounts.setBudget('acct_123', { monthly_budget_cents: 5000 }); // 50.00 USD a month
await stack.accounts.setBudget('acct_123', { monthly_budget_cents: null }); // no budget
```

- Only the owner or an admin changes a budget. An agent cannot.
- Lowering a budget applies at once, and works without controls.
- Raising or removing one counts as loosening and needs your approval in a browser.
- Setting or raising a budget needs controls. Without them the call answers 403 BUDGET_NEEDS_CONTROLS.
- The tool is stack_set_account_budget.

## Reference

Every billing route is on [Billing](/docs/api/billing). To pay suppliers with your card, see [Your own card](/docs/account/card).
