Cloud promotional money

Promotional money is a balance we grant to a Space so a customer can buy a paid plan or a published package of AI Credits or Infrastructure Units from us. It is money, not a usage unit: it has a currency and an amount in that currency’s minor units, it has an expiry, and it pays an exact price the commercial kernel has already frozen.

It is deliberately not cash. It cannot be withdrawn or transferred to another account, and there is no free exchange between the promotional-money and usage-unit ledgers. The convertible: false flag means exactly that: a client must not invent an exchange rate or move an arbitrary amount. A customer can still spend promotional money on a published usage-unit package; that is an exact commerce order with a frozen price, not a balance conversion.

Promotional money is also not the same thing as AI Credits or Infrastructure Units. Those meter consumption: one AI operation or one infrastructure unit of work, priced by a frozen price version. Money settles an exact price and has no price version of its own. The two live in separate ledgers and are shown as separate cards.

How promotional money is granted

There are two ways, and both leave an attributable record.

A promotion code. An operator creates a campaign in Operator console → Loyalty and chooses Promotional money as the reward. The campaign states three things, and it must state all three:

• the currency (a three-letter code such as RUB);
• the amount in that currency’s minor units (for example 250000 is 2 500.00 RUB);
• the validity in days, which is how long the money lives after it is granted.

The amount is also the campaign’s reward units — one number, one fact. A campaign whose two figures disagree is rejected rather than silently preferring one of them.

Activate the campaign and give the code to the customer. When they redeem it in the cabinet, the money is credited as an immutable lot in their Space’s promotional balance. The lot records where it came from (that campaign), how much it is, and when it expires.

An operator can instead issue a Team package code: one month of Team for five seats at the price published when the campaign was created. Redeem it in your Personal Space. It creates a dedicated, expiring promotional lot; it does not increase the ordinary balance and cannot pay for Pro, AI Credits or another package. In the Team checkout, select the package quote and pay once from that lot. There is no card charge or automatic renewal. If the Team price changes later, this lot still pays the promised price, provided the current market and legal terms allow the sale.

An operator decision. When there is no campaign — a goodwill grant, a partner agreement, a beta programme — an operator adjusts the balance directly, in Operator console → Promotional money, under two-person control. One operator proposes the amount with a reason code and a digest of the supporting evidence; a different operator approves or rejects it. Nothing is credited until the second operator approves, and a rejected case is final: it is never re-decided.

The same two-person rule governs taking money back. A clawback names the exact lot it takes from and may only take what that lot still holds — never money the customer already spent, never money held by a checkout in progress, and never more than the lot has left.

How promotional money is spent

At plan checkout the customer picks Pay from → Promotional balance instead of the card. Under Billing → Top up the balance, each published AI-credit or Infrastructure Unit package separately offers Use promotional balance when the selected Space has enough money. Everything else is the same exact purchase: the chosen product, the same confirmation step, and the same idempotency contract.

A promotional-balance plan checkout pays one period and does not enable automatic renewal. The renewal control is shown only when paying by card. A direct API request combining payment_source: "bonus" with auto_renew: true is refused with bonus_renewal_unavailable before promotional money is spent. A usage-unit purchase credits the package immediately after the internal bonus hold settles; it never creates a payment-provider operation or waits for a bank webhook.

If earlier account credit covers the whole price of a card-selected checkout, no card payment or renewal mandate is created. That purchase also covers one period only; auto_renew: true is refused with balance_renewal_unavailable before the balance is debited. Turn off automatic renewal and buy the next period once the current paid period ends; a fresh same-plan Pro or Pro+ checkout during the existing paid period is refused with same_plan_period_active so remaining paid time is not lost. A partially covered checkout may still use the card for the remainder and create a mandate.

The top-up history labels the payment source. A package paid from promotional balance has an internal ledger receipt instead of a fiscal-provider receipt. That receipt names the exact settled bonus reservation, the exact usage-wallet lot it created, the amount spent, the currency and the number of units credited. It stays available when the purchase is opened from history. A missing internal receipt is reported as unavailable; the cabinet never describes it as a fiscal receipt that is still being issued.

Promotional money pays the whole price or none of it. There is no partial application, and this is a rule the commercial ledger enforces: a settled payment has to equal the frozen order total exactly. A half-bonus, half-card order would be two money sources for one order, which the accounting, dispute and fiscal records do not represent.

When the balance cannot cover the price, checkout is refused and the customer is told the exact figures:

• the exact price of the plan or usage-unit package,
• what their promotional balance holds,
• how much they are short.

The figures appear beside the plan purchase controls, so the customer does not need to search the Usage section after a refusal.

If card payments are enabled, checkout offers the card instead. In a bonus-only deployment, add enough promotional balance with a code or contact support before trying again. Nothing was charged, nothing was reserved, and the balance is untouched.

If the balance was sufficient when the request was priced but another checkout spent it before the money could be held, the second checkout is refused with the same refusal. The customer is never charged by surprise.

Expiry

Each grant expires on its own date, visible in the statement. Expired money was never spent and is not counted in the available balance; the balance card shows it separately so nothing disappears silently. The statement shows the next amount about to expire and its date, so a customer can decide to use it.

Hold on to a promotion code until you need it: the validity clock starts when the code is redeemed, not when the campaign is created.

Statements

Billing → Promotional money statement lists every movement: the grant, each hold, each settlement, each release, a refund returning money to the balance, an expiry, and any operator clawback. Each line names the movement and the amount, and a line tied to a lot shows when that money expires.

A purchase paid from the balance appears twice, in the two ledgers it belongs to: the plan or credit package appears in the ordinary payment history, and the money leaving the balance appears in the promotional statement.

When you switch Spaces, the cabinet clears the previous Space’s balance and reloads the selected one. If the balance cannot be read, the cabinet shows that it is unavailable rather than treating it as zero. In Usage → Spend limit, wait for the selected wallet’s current limit to load before saving a change. If you switch Spaces or change the wallet while confirming a spend limit, the change is cancelled; review the selection and submit it again. The same protection applies to purchases awaiting confirmation: they never move to a different Space.

Refunds

Promotional money never travelled through a payment provider. The cabinet has no refund button; a canceled plan runs to the end of its paid period. Contact support about a disputed purchase. A full refund of a bonus-paid Team period waits until the shared Space has become read-only on the shared server; a server outage leaves the request pending without moving the bonus balance. Once confirmed, each spent promotional lot returns to the purchaser’s Personal Space with its original expiry. It does not create a fresh validity period; already expired money remains expired. A partial Team bonus refund is not available. Other bonus purchases are not automatically refunded.

Operator reference

All operator actions for promotional money are under Operator console → Promotional money and require step-up confirmation. Proposing, deciding, granting and taking back are four separate actions, so the audit trail records who did which. Read-only access uses one permission and mutating actions another, granted separately from promotion management, so an operator who runs campaigns does not thereby gain the ability to mint spendable balance.

API surface, for operators who automate:

• GET /api/v1/cloud/operator/bonus/lots?space_id=…&currency=… — the Space’s lots, including the untouched remainder a clawback may take.
• GET /api/v1/cloud/operator/bonus/adjustments?space_id=… — the decision queue for one Space.
• POST /api/v1/cloud/operator/bonus/adjustments — propose a grant or a clawback case.
• POST /api/v1/cloud/operator/bonus/adjustments/{id}/decide — approve or reject, as a different operator.
• POST /api/v1/cloud/operator/bonus/adjustments/{id}/grant — execute an approved grant, creating the lot.
• POST /api/v1/cloud/operator/bonus/adjustments/{id}/clawback — execute an approved clawback.

API surface for the cabinet and for customer-side automation:

• GET /api/v1/cloud/billing/bonus?currency=… — the Space’s promotional balance and the first page of its statement.
• POST /api/v1/cloud/subscriptions/checkout with "payment_source": "bonus" — pay for a plan from the promotional balance. Omitting the field, or sending "card", uses the ordinary payment path. Manual invoices refuse the field, because a bank transfer is not a promotional-balance payment.
• POST /api/v1/cloud/billing/wallet-topups?workspace_id=… with a published product_code and "payment_source": "bonus" — buy the exact AI-credit or Infrastructure Unit package from promotional balance. Do not send payment_method on this path; payment_method is only for the external provider path.
• GET /api/v1/cloud/billing/wallet-topups?workspace_id=… and GET /api/v1/cloud/billing/wallet-topups/{order_id}?workspace_id=… — read the source and durable receipt of a previous top-up. Bonus-funded purchases return payment_source: "bonus" and ledger_receipt; provider-funded purchases return payment_source: "card" and their fiscal receipt state.
• GET /api/v1/cloud/billing/status reports card_payments_enabled and bonus_payments_enabled separately. The older payments_enabled field only says the checkout service is installed; it does not mean this deployment accepts card charges.

Starting a wallet top-up is an interactive money and ledger mutation with a fresh
checkout proof. It is deliberately absent from the SDKs, CLI and MCP tools. The
REST paths above support the cabinet and its receipt view; they are not approval
to automate promotional spending or provider charges with a reusable client
credential.

Keep one idempotency key for one exact source and request. An exact retry with the same key returns the same purchase even when that purchase has depleted the promotional balance; it does not spend again. Changing from promotional balance to card payment, or back, is a different purchase attempt and must use a new key.