Prepaid service credit
Your organization pays for Kilimanjaro from one prepaid service credit balance. You add to it by topping up, and your plan, any governance capacity packs, and any priced usage draw from it. The card processor only collects your top-ups. It never bills you for a plan.
This guide covers how the balance works. For what each tier includes and what is metered, see Billing.
1. How the balance works
- One balance per organization. Every project in the organization draws from the same balance, whichever region the project lives in.
- It belongs to your billing entity. Your organization has a commercial relationship with the Kilimanjaro billing entity it signed up with. That entity's jurisdiction decides currency, tax treatment and which funding methods are available. It does not depend on where your projects are homed.
- What draws from it. The plan sticker is drawn at the start of each billing period, pro-rated if you change plan mid-period. Governance capacity packs are drawn as their own monthly line. Priced usage above your allowance is drawn only on the dimensions where you have turned Headroom on.
- It does not expire. Purchased credit stays on your balance until it is used or refunded under the policy in §6.
- It is for Kilimanjaro services only. Credit cannot be transferred to another organization or billing entity, and it cannot be converted to cash except by a refund under §6. To move between billing entities, take a refund from one and top up the other.
- Promotional and courtesy credit is separate. It is tracked apart from credit you purchased, and it is not refundable.
2. Topping up
A top-up is a payment you make to add credit. The credit appears on your balance when the payment is confirmed. Returning from the payment page does not by itself add credit.
- Minimum: one billing period's plan sticker.
- Maximum, per transaction: the annual prepayment for your tier.
- No balance cap.
- Base Camp has no plan sticker. Buying a paid plan adds at least the first period's sticker (or the annual prepayment) to your balance.
- Card processing fees are ours. Your balance is credited with the full amount you paid.
POST <orgSlug>.api.k9o.io/billing/wallet/top-up
{ "amount": <Money>, "forPlan": { "tier": "<tier>", "interval": "monthly" | "annual" } }
forPlan is optional. With it, the amount is bounded by the target plan's sticker and annual prepayment rather than by your current tier. The response is a hand-off to the payment page, not a credit. Every request carries an Idempotency-Key.
Top-ups can be paused while an account is under review. In that case the request is refused with 409 K9O_STATE_CONFLICT and context.reason: "account_under_review".
3. Automatic top-up
Automatic top-up charges your saved card when your balance falls to a threshold, so a period open never meets an empty balance.
PUT <orgSlug>.api.k9o.io/billing/wallet/auto-top-up
{ "enabled": true, "thresholdCents": <n>, "amountCents": <n>, "perTransactionLimitCents": <n> }
- Turning it on is an explicit mandate. You state the threshold that triggers a top-up and the most that any single automatic charge may be.
- It needs a card on file. Without one the request is refused with
409 K9O_STATE_CONFLICTandcontext.reason: "no_card_on_file". - The amount defaults to the minimum top-up. The threshold is your setting.
- You can turn it off at any time.
4. Reading your balance
GET <orgSlug>.api.k9o.io/billing/wallet
GET <orgSlug>.api.k9o.io/billing/wallet/statement?cursor=<c>&limit=<n>
The balance response includes status, which is one of active, tolerance or suspended_read_only (§7). The statement lists every credit and debit with its source, direction, amount and time.
5. Plans and annual prepayment
You change plan with POST <orgSlug>.api.k9o.io/billing/plan { tier, interval }.
- Your balance has to cover the change. If it does not, nothing changes and the request is refused with
409 K9O_STATE_CONFLICT,context.reason: "insufficient_balance", together with the amount required, the amount available, and a recommended top-up. - Upgrades take effect now and load the pro-rated difference for the rest of the period. Downgrades do not refund the sticker already drawn.
- A change that raises your recurring spend asks you to confirm with a step-up check.
Annual plans. Choosing an annual term prepays twelve months at the discounted price into your balance: twelve times the monthly price times (1 minus the annual discount). The discount is 20% on a paid Cloud tier.
- Renewal. An annual plan renews automatically for another twelve months at the annual price then in effect, funded from your balance (through your automatic top-up mandate if the balance is short). Choosing the annual term at the price and terms shown is your consent to renewal. You are shown the renewal price and frequency, we notify you 30 days before each renewal, and you can turn renewal off at any time before then.
- Cancelling early. The refund is the amount you prepaid, less the undiscounted monthly price in effect when you bought the term for each month you have used. A month that has begun counts as used.
Worked example. You buy an annual plan on a tier whose monthly price is $899.00.
| Prepaid for twelve months at 20% off | 12 × $899.00 × 0.80 = $8,630.40 |
| Cancel during month 4, so 4 months count as used | 4 × $899.00 = $3,596.00 |
| Refund | $8,630.40 − $3,596.00 = $5,034.40 |
The discount you received on the months you used is recovered at the undiscounted price. If you used at the undiscounted price as much as you prepaid, the refund is zero. The discount you earned on overage during the term is not recovered. The figures here use an example price; yours come from the rate card at the time you buy.
6. Refunds
This is the text shown to you before you buy.
Refunds
Purchased service credit does not expire. Subject to the applicable terms, unused purchased credit may be refundable when you voluntarily close your billing account or when you cancel an eligible prepayment. Amounts attributable to services already consumed, promotional or courtesy credit, and amounts that are subject to a valid outstanding balance are not refundable except where required by law.
Where a refund relates to a card-funded payment, the refund will normally be processed to the original payment method.
Annual plan cancellation
Annual pricing includes a discount based on a 12-month commitment. If you cancel before the end of the annual term and the plan is refundable under these terms, the months already used will be charged at the applicable standard monthly price and the remaining prepaid amount will be refunded. Usage charges outside the plan allowance are calculated separately and are not included in the annual-plan refund calculation.
In practice:
- What can be refunded. Unused balance from a prepayment you do not plan to use, and a valid, non-promotional remaining credit balance when you close your billing account.
- What cannot. Promotional, courtesy or free-trial credit, charges for resources you actually used (including services left running), and amounts you owe.
- Set-off comes first. An amount you owe is set off against your refundable balance, and the remaining net balance is refunded. We do not keep a large credit because of a small amount owed.
- Where it goes. Refunds go to the original payment method. If the card network's refund window has passed or the card is closed, the refund is paid by bank transfer.
7. When the balance runs out
If your balance cannot cover the plan sticker at period open:
- Automatic top-up runs, if you have it on.
- A tolerance of 10% of the pro-rated sticker applies. Your balance
statusistolerance. - The organization is suspended to read-only. Export and audit access continue.
statusissuspended_read_only. - After 30 days of read-only, application data is purged under the Zero-Residue process: cryptographic key destruction and physical erasure, recorded in a platform-signed receipt.
You are warned 7 days and 1 day before the purge. The organization owner can place a purge hold (and release it) to stop the countdown, with a step-up check.
The purge removes your application data. Billing and tax records are kept separately, under their own retention rules.
8. Tax and invoices
Tax is extra. When tax is due depends on your billing entity's jurisdiction and your location. A top-up may be taxed when it is received, or only when the credit is consumed. Which applies is set per jurisdiction.
We record the funding transaction and the taxable supply as separate records, and issue a tax invoice either at top-up or at each draw, as your jurisdiction requires. Your invoices are listed at GET <orgSlug>.api.k9o.io/billing/stripe/invoices.
9. Who can do what
| Roles | |
|---|---|
| View the balance, statement, plan, invoices | ORG_OWNER, ORG_ADMIN, ORG_BILLING_ADMIN, ORG_BILLING_VIEWER |
| Top up, set automatic top-up, change plan | ORG_OWNER, ORG_BILLING_ADMIN |
| Place or release a purge hold | ORG_OWNER, with a step-up check |
ORG_ADMIN can read billing and receives the purge warnings, but money and plan authority stay with the owner and the billing admin.
10. See also
- Billing: what each tier includes, Headroom, and
meta.cost. - Sovereignty guide: the Zero-Residue purge and export.
- Pricing page: the rate card.