Chargeback
1 |
6 |
||
2 |
7 |
||
3 |
8 |
||
4 |
9 |
||
5 |
10 |
Overview
Chargeback lets the platform operator price each tenant’s cloud resources and generate bills and invoices. A tenant is a CloudStack domain, and its Tenant ID is the CloudStack domain ID.
Billing is calculated from reserved resource limits (the CloudStack allocation), not from measured usage. A tenant’s bill is the sum, across 12 resource types, of limit multiplied by unit price. Every bill and PDF states this in its footer.
Every tenant starts with all prices at 0. Billing is off by default, so the tenant is in showback mode: you can see what the tenant would be charged, but the tenant is not marked as billable.
Note
Chargeback is for operators. All chargeback actions require root access. Non-root users cannot open the Billing tabs or call the API.
Before You Begin
Confirm the following before you set up billing:
You are signed in as a root user.
The tenant exists in Control Center, and you know its Tenant ID (see How to Open Chargeback).
You have decided the monthly price for each of the 12 resource types (see Pricing Model).
How to Open Chargeback
In Control Center, open Tenants.
Click the tenant name to open its detail page.
Check the Overview section. The Tenant ID shown there is the value used in the API and in invoice filenames.
On the Tenants list, each tenant has a billing toggle. Turning it on opens the Enable Billing confirmation dialog. The dialog reads: Enable charge-back billing for {name}? Pricing and billing tabs will become available. Turning it off opens Disable Billing.
The tenant detail page has these tabs: Overview, Users, Limits, Pricing, Schedule Change, Billing, and IDP Configuration. The Pricing, Schedule Change and Billing tabs are hidden until billing is enabled.
Key Concepts
Term |
Meaning |
|---|---|
Tenant ID |
The CloudStack domain ID. Used in every API path and in invoice filenames. |
Tenant pricing |
The monthly unit price for each of the 12 resource types, plus the currency. Default currency is USD. |
Billable flag |
The |
Scheduled price change |
A future set of prices with an effective date. It replaces the active prices automatically on the first read after that date. There is no scheduled job. |
Current bill |
The bill for the current calendar month, calculated from the current CloudStack limits. |
Upcoming estimate |
A projected bill for next month. Marked as an estimate. |
Snapshot |
A stored copy of the current month’s bill, saved as an invoice. |
Invoice |
A stored bill for one tenant and one month. The period is written as |
Set Up Billing for a Tenant
Follow these steps in order. You can turn billing on at any point, but prices must be set before the bill is meaningful.
Step |
Where |
What you do |
|---|---|---|
1 |
Pricing tab |
Enter a price for each resource type you charge for. Leave a price at 0 to charge nothing for that resource. Click Save. |
2 |
Schedule Change tab |
Optional. Enter the new prices and an effective date in the future. Saving this replaces the scheduled change, if one already exists. |
3 |
Tenants list |
Turn on the billing toggle and confirm Enable Billing. The Billing tabs appear. |
4 |
Billing tab, Current Bill |
Check that the line items and total match your expectations. |
Warning
Saving on the Pricing tab replaces the whole price set. Any scheduled change is cleared as well, because the Save action sends only the active prices. If you need a scheduled change, enter it again after you save. See Known Behavior.
Pricing Model
Prices are monthly per unit, in one currency. There are 12 resource types. Each has a fixed ID, which is used in the API.
ID |
Resource |
Price field |
Unit |
|---|---|---|---|
0 |
Instances |
|
per instance |
1 |
IPs |
|
per IP |
2 |
Volumes |
|
per volume |
3 |
Snapshots |
|
per snapshot |
4 |
Templates |
|
per template |
5 |
Projects |
|
per project |
6 |
Networks |
|
per network |
7 |
VPCs |
|
per VPC |
8 |
CPUs |
|
per CPU |
9 |
Memory (MB) |
|
per MB of memory |
10 |
Primary Storage (GB) |
|
per GB |
11 |
Secondary Storage (GB) |
|
per GB |
Currency. The default is USD. Control Center shows the symbol for USD, EUR, GBP and INR. Other currency codes are shown as a prefix before the amount.
Prices are not validated. The system accepts zero and negative prices. A negative price produces a negative charge.
Current Bill and Upcoming Estimate
Current Bill
The Current Bill sub-tab shows the bill for the current month, using the current CloudStack limits.
To download it as a PDF, click Download PDF.
Upcoming Estimate
The Upcoming Estimate sub-tab projects next month’s bill.
If a scheduled price change takes effect on or before the first day of next month, the estimate uses the scheduled prices.
Otherwise it uses the current prices.
Limits are always the current CloudStack values.
The estimate is marked as an estimate. It is not a stored invoice and does not change any data.
Bill Calculation
For each of the 12 resource types, the system:
Reads the tenant’s resource limit from CloudStack for the tenant’s domain.
If the limit is
-1(unlimited), or the resource type is missing from the CloudStack response, skips the resource. Nothing is charged and no line is shown.Otherwise, calculates
charge = limit × unit priceand adds a line to the bill. A limit of0produces a line with a charge of 0.
The total is the sum of all charges.
Example: a tenant has a limit of 10 instances at $25 per instance, and a limit of 2 IPs at $2 per IP.
Resource |
Limit |
Unit price |
Charge |
Total |
|---|---|---|---|---|
Instances |
10 |
$25.00 |
$250.00 |
|
IPs |
2 |
$2.00 |
$4.00 |
|
Total |
$254.00 |
Billing History and Invoices
A snapshot calculates the current month’s bill and saves it as an invoice. There is one invoice per tenant per month.
Snapshot on the Billing History sub-tab creates the invoice for the current month.
Snapshots are also taken automatically each time a tenant is activated or deactivated.
Taking a snapshot for a month that already has an invoice overwrites it. The stored line items, total and currency are replaced with the values from the current limits and prices.
A stored invoice keeps its values after later price changes. Only a new snapshot changes it.
The Billing History tab lists stored invoices, newest month first. Each row has a PDF download.
Note
Invoices are not immutable. A later snapshot for the same month replaces the earlier one. See Known Behavior.
PDF Invoices
Invoices can be downloaded as PDF in two ways:
Current bill: from the Current Bill sub-tab, using Download PDF.
Stored invoice: from the Billing History sub-tab, using the PDF button on the row.
The PDF is A4 portrait and contains:
The title Chargeback Invoice and the subtitle Karios Cloud Platform.
The tenant ID.
The billing period, for example
May 2026.The currency and the generation date.
A table with the resource, limit, unit price and charge for each line.
The total.
An estimate also shows Status: Estimate (not finalised) and a note that limits may change.
The footer on every PDF reads: Charges are based on reserved resource limits (allocated capacity), not actual consumption.
The filename is invoice-<tenant_id>-<YYYY-MM>.pdf.
API Reference
All endpoints are under /api/v2/chargeback/tenants/{id}/, where {id} is the Tenant ID. All endpoints require root access.
Authentication
Send a bearer token with every request:
Authorization: Bearer <token>
Missing or invalid token:
401.Valid token for a non-root user:
403with the message Insufficient permissions: root access required.
The gateway also requires the USER_MANAGE permission for /api/v2/chargeback/*.
Endpoints
Method |
Path (below |
Purpose |
|---|---|---|
GET |
|
Get the active prices. Applies a due scheduled change first. |
PUT |
|
Save prices. Replaces the whole price set. Optionally schedules a future change. |
PUT |
|
Turn billing on or off. |
GET |
|
Live bill for the current month. |
GET |
|
Estimate for next month. Marked |
GET |
|
PDF of the current month’s live bill. |
POST |
|
Save the current month’s bill as an invoice. Overwrites an existing invoice for that month. |
GET |
|
List stored invoices, newest month first. |
GET |
|
PDF of a stored invoice. |
Save prices (PUT /pricing)
PUT replaces the whole price set. Any price you leave out is stored as 0. Include every field you want to keep.
{
"currency": "USD",
"price_per_instance": 25.00,
"price_per_ip": 2.00,
"price_per_volume": 0.10,
"price_per_snapshot": 0.05,
"price_per_template": 0,
"price_per_project": 0,
"price_per_network": 1.00,
"price_per_vpc": 5.00,
"price_per_cpu": 10.00,
"price_per_memory_mb": 0.002,
"price_per_primary_storage_gb": 0.08,
"price_per_secondary_storage_gb": 0.02,
"upcoming_pricing": {
"currency": "USD",
"price_per_instance": 27.00,
"price_per_ip": 2.00
},
"upcoming_effective": "2026-11-01T00:00:00Z"
}
Rules for the scheduled change fields:
upcoming_pricingandupcoming_effectiveare both optional, but each requires the other.upcoming_pricingtakes the same fields as the top-level body. The example above shows only two; send all of them in a real request.upcoming_effectiveis an RFC 3339 timestamp, usually the first day of a month. It must be in the future when you save.
Enable or disable billing (PUT /billable)
Request:
{"is_billable": true}
Response:
{"tenant_id": "<domain-id>", "is_billable": true, "message": "Billing enabled"}
The message is Billing disabled when the value is false.
Bill response (GET /bill, GET /bill/upcoming)
{
"tenant_id": "<domain-id>",
"period": "2026-10",
"currency": "USD",
"line_items": [
{ "resource": "Instances", "limit": 10, "unit_price": 25, "charge": 250 }
],
"total": 250
}
is_estimate: true appears only on GET /bill/upcoming.
Errors
Errors use this shape:
{
"code": "",
"message": "Pricing has not been configured for this tenant.",
"correlation_id": "<id>"
}
code is empty for chargeback errors. Use message to identify the error.
Status |
Message |
When |
|---|---|---|
404 |
Pricing has not been configured for this tenant. |
No pricing row exists. Returned by pricing, bill, snapshot and billable endpoints. |
404 |
No invoice was found for the selected tenant and period. |
No stored invoice for that period. Returned by the invoice PDF endpoint. |
400 |
The effective date must be in the future. |
|
400 |
An effective date is required when upcoming pricing is set. |
|
500 |
The cloud service is unavailable. Try again later. |
The CloudStack limits call failed. |
Known Behavior
These points affect how you read a bill or an invoice. Read them before you rely on the billable flag or on stored invoices.
The billable flag does not control billing. Bills, snapshots and PDFs are produced for every tenant, whether or not billing is enabled. Turning billing off hides the Billing tabs in Control Center and removes the tenant from the billable count in statistics. It does not stop invoices from being created.
Invoices can be replaced. A snapshot for a month that already has an invoice overwrites it. Activating or deactivating a tenant also snapshots the current month, so it overwrites that month’s invoice.
Saving prices clears any scheduled change. The Save action sends only the active prices. Any scheduled change is cleared, so re-enter it after saving.
Reads can change data. When a scheduled change is due, the first read of pricing, the bill, a snapshot or a bill PDF applies it to the active prices and clears the scheduled fields. There is no background job, so the change takes effect on the first read after the effective time.
The Control Center wording overstates the flag. The disable dialog says Billing and pricing data will be hidden. The enable dialog says billing will resume. Both describe the interface. Bills and invoices are produced whether or not billing is enabled.
Tenants created before chargeback have no pricing row. Pricing, bill and snapshot calls return 404. Snapshots for these tenants are skipped without an error.
Troubleshooting
Symptom |
What to check |
|---|---|
Billing tabs are missing |
Billing is off for this tenant. Turn on the billing toggle on the Tenants list. |
Pricing tab shows Pricing has not been configured |
The tenant has no pricing row, usually because it was created before chargeback. Save prices once to create the row. |
Bill total is 0 |
All prices are 0, or every limit is unlimited ( |
A resource is missing from the bill |
Its limit is |
The cloud service is unavailable when opening the bill |
CloudStack did not respond. Try again later. No data is changed. |
Scheduled change disappeared |
A Save on the Pricing tab clears it. Enter the scheduled change again. |
Invoice total changed for a past month |
A snapshot, or a tenant activate or deactivate, overwrote that invoice. Check the timing of the last snapshot. |
PDF total differs from the line items by a cent |
Values are stored unrounded. The PDF shows two decimals, so rounding can differ. |
Quick Reference
Tenant ID = CloudStack domain ID.
Bill = sum over 12 resources of
limit × unit price, skipping-1.Default = all prices 0, billing off.
Save prices = replaces all prices and clears any scheduled change.
Snapshot = stores the current month as an invoice. Overwrites the same month.
PDF =
invoice-<tenant_id>-<YYYY-MM>.pdf.Access = root only.