STACK
MENU
DOCS / THE ACCOUNT / PREPAID CREDIT

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.

Before you start

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

Add credit

prompt
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. To pay suppliers with your card, see Your own card.

Prepaid credit | Docs