---
title: Packages
description: One package per account: a limit in percent of the plan, top-ups and the minimum purchase, which keys spend the package, freezing, notices, and how a package differs from the wallet.
keywords: package, prepaid, limit, plan, top up, top up to plan, minimum purchase, freeze, 402
group: account
---

## What a package is {#what keywords="package, prepaid, limit, account"}

A package is a **prepaid token limit**, bought in advance at a volume discount. It is spent in tokens rather than in money, and on its own it never draws on the wallet.

**An account holds one package.** The first purchase opens it, and every later purchase tops up that same package. There is no choosing where a purchase lands: there is nowhere else for it to land.

The package is spent by every key of the account that you have allowed to spend from it — and which keys those are, you decide key by key.

## Plan and limit {#plan keywords="plan, limit, percent, pro, max, ultra"}

The **plan** is the largest single purchase of the package. The console names the package's group after it — **Pro, Max or Ultra** — and measures what is left against it. A purchase smaller than the plan never lowers it; a larger one raises it to its own size. No privileges come with a plan: it is only the yardstick the gauge is drawn against.

What is left of the package is shown as a **limit in percent of the plan**: how much of the plan can still be spent. When a top-up leaves more than the plan, the gauge stands at 100 %. The gauge changes colour when what is left drops below half and below 20 %.

## Buying and topping up {#purchase keywords="purchase, top up, top up to plan, minimum purchase, ladder"}

A purchase is priced **by the size of that purchase itself** on the published price ladder: the larger the purchase, the cheaper each token in it. A top-up costs what a purchase of its size costs — neither what is left nor the plan changes the price.

The **minimum purchase**, the first one and every top-up alike, is **30 million tokens**.

The package card on the billing screen carries two buttons:

:::deflist
| Button | What it does |
| --- | --- |
| Top up | Opens a purchase of any size from the minimum up — it is added to what is left. |
| Top up to plan | Offers straight away the size that brings what is left back to the plan — but never less than the minimum purchase. |
:::

Nothing is charged until you go to the payment page. The limit is topped up once the payment is credited.

> [How a payment goes →](/en/billing) [The price list](https://kumorouter.com/en/pricing)

## How a package is spent {#burn keywords="package, limit, minimum purchase, input, output, cache, reasoning"}

An account holds **one package**, and every key of the account that spends from the package draws on it. The package's remaining capacity is shown as a **limit in percent** of the plan, not as a raw token count and not as a formula you would reproduce yourself.

Models have **different prices**, and a request to a pricier model takes more from the package than the same request to a cheaper one. The console and the catalogue show each model's prices.

**Input is everything sent to the model** — the system prompt, the message history, the tool definitions, the attached files, and anything read from or written to the cache. **Output is everything the model generated**, reasoning tokens included, even when you do not see them in the answer. Both count toward what the package spends on a request.

Token quantities and the package's own limit are two different figures, and the console prints them apart: the quantities a request went upstream with are on the activity screen and in an opened call's card, and the package's remaining limit is shown in percent on the billing screen. They are never added into one figure anywhere.

The practical consequence: a long conversation history is input, and it is paid for again on every request. In agentic use it is usually that history, rather than the model's answers, that makes up most of the spend.

## Which keys spend the package {#keys keywords="key, package, balance, after the package, key limits, how it is charged"}

Each key chooses what it spends from: **the package** or **the balance**. The choice is not final — change it any time in the "Choose how it is charged" window, which opens when you press the key's cell in the "Billing" column on the keys screen (the "Spends from" row).

For a key that spends from the package, the same window sets what happens when the package limit runs out (the "After the package" row):

:::deflist
| Choice | What happens once the limit is used up |
| --- | --- |
| stop | The key refuses requests until you top the package up. |
| balance | The key carries on from the balance, at wallet prices. |
:::

Until you choose, a key spends from the package when the account has one and stops when the limit runs out; without a package the key spends from the balance.

Each key can also carry **its own package limits**: how much it may spend from the package per day, per month and ever. An empty field means no limit. That way one hungry agent cannot eat the package the other keys rely on.

A project changes none of this: it is a label over keys, not a source of money.

> [Keys →](/en/keys) [How the wallet counts →](/en/billing)

## Freezing {#freeze keywords="freeze, pause, package, 403"}

The package can be **frozen** with the switch in the "Details →" window on the package card. While it is frozen, keys that spend from the package refuse requests with **`403`** `package_frozen` — and they do **not** fall back to the balance, even when "after the package — balance" is chosen for them. What is left of the package is not spent and does not go anywhere.

The same switch unfreezes it. Keys that spend from the balance are not affected by a freeze.

This freeze is yours. Do not confuse it with a freeze by Kumo after a long gap without purchases: this switch does not lift that one — a purchase does.

## Notices {#notices keywords="notices, notifications, 20 %, used up, remaining"}

The console reminds you about the package in its notifications window twice: when **less than 20 %** of the plan is left, and when **the limit is used up**. Top the package back above the threshold and drain it again, and the reminder comes again.

## When the limit runs out {#exhausted keywords="402, exhausted, refusal, stop, balance"}

What happens to a request is decided by the key's "After the package" choice.

- **stop** — the request is refused with **`402`** and the code `insufficient_package_balance`, a code separate from the wallet's, because the cure is different: buy a package rather than top up a balance.
- **balance** — the request goes through and is paid from the balance at wallet prices. If the balance is empty too, the refusal is the wallet's: `402` `insufficient_wallet_balance`.

A request started while something was left may, on its way, spend more than the package still held. For a key on "stop", that overrun is **not** taken from the balance — Kumo absorbs it.

Do not confuse it with scope: a call naming a model outside the key's whitelist is a `403`, and it is cured by a different key rather than by a purchase.

> [Every gateway status →](/en/errors)

## Term and refunds {#expiry keywords="term, three months, frozen remainder, refund, remainder"}

What is left of a package **does not expire automatically**. But if the package has seen **no purchase for about three months**, Kumo may **freeze** its unspent remainder. That is Kumo's decision, not a timer. The remainder stays with the account, but while it is frozen, keys that spend from the package refuse requests with **`403`** `package_frozen`.

The switch in the "Details →" window does not lift this freeze — **the next purchase** does: it unfreezes the remainder. **Every purchase restarts that period.**

The price of a package, including its unspent remainder, **is not refunded**. The wallet's money balance is outside this rule. The exact terms are in the [public offer](https://kumorouter.com/en/legal).

## A package's price in roubles {#roubles keywords="roubles, rate, package price, rounding, payment"}

A package is priced **in dollars**: the platform buys the capacity from its suppliers in dollars, and the dollar price does not move with the rouble.

The rouble figure on the storefront is that same dollar restated at the **accounting rate** of the Bank of Russia. It is there to orient you.

What you are charged is a different figure: it is computed at the **payment's rate**, pinned at the instant the payment is created, and raised up to the next ten roubles. The purchase window shows it before you go to the payment provider — that is the figure the bill carries.

So the roubles on the storefront and the roubles in the purchase window may differ, in either direction: the two rates are different and both move from day to day. The package's dollar price is the same one throughout.

The mark tells the two apart: a rouble figure with an **≈** is a restatement, one without it is the figure you will be charged. That is why every rouble on the storefront carries the mark, while in the console only the rows a price is built from do — the price itself and the amount to pay carry none.

> [About both rates →](/en/billing)

## Package or wallet {#compare keywords="comparison, wallet, package, choosing"}

:::matrix
| | Wallet | Package |
| --- | --- | --- |
| What is shown | dollars | a limit in percent of the plan |
| Funded by | any amount | a purchase of 30 million tokens or more, on the price ladder |
| How many per account | one | one |
| Charging rule | a price per unit of every dimension | a rate set by Kumo per model, against the package limit |
| Refusal when short | `402` `insufficient_wallet_balance` | `402` `insufficient_package_balance` |
:::

Running both is legitimate and ordinary: some keys spend from the package, some from the balance, and a key on the package can carry on from the balance once the limit runs out. Each key's spend is visible on its own — from the package and from the balance apart. What cannot be done is adding the two into one number: a sum of dollars and package tokens has no unit.

> [The price list](https://kumorouter.com/en/pricing) [Where to watch spend →](/en/usage)