Chargeback

Table of Contents

1

Overview

6

Bill Calculation

2

Before You Begin

7

Billing History and Invoices

3

Set Up Billing for a Tenant

8

PDF Invoices

4

Pricing Model

9

API Reference

5

Current Bill and Upcoming Estimate

10

Known Behavior

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

  1. In Control Center, open Tenants.

  2. Click the tenant name to open its detail page.

  3. 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 is_billable setting on the tenant’s pricing row. It controls whether the Billing tabs are shown and whether the tenant is counted as billable in tenant statistics. It does not change how bills are calculated. See Known Behavior.

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 YYYY-MM.

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

price_per_instance

per instance

1

IPs

price_per_ip

per IP

2

Volumes

price_per_volume

per volume

3

Snapshots

price_per_snapshot

per snapshot

4

Templates

price_per_template

per template

5

Projects

price_per_project

per project

6

Networks

price_per_network

per network

7

VPCs

price_per_vpc

per VPC

8

CPUs

price_per_cpu

per CPU

9

Memory (MB)

price_per_memory_mb

per MB of memory

10

Primary Storage (GB)

price_per_primary_storage_gb

per GB

11

Secondary Storage (GB)

price_per_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:

  1. Reads the tenant’s resource limit from CloudStack for the tenant’s domain.

  2. 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.

  3. Otherwise, calculates charge = limit × unit price and adds a line to the bill. A limit of 0 produces 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: 403 with the message Insufficient permissions: root access required.

The gateway also requires the USER_MANAGE permission for /api/v2/chargeback/*.

Endpoints

Method

Path (below /tenants/{id})

Purpose

GET

/pricing

Get the active prices. Applies a due scheduled change first.

PUT

/pricing

Save prices. Replaces the whole price set. Optionally schedules a future change.

PUT

/billable

Turn billing on or off.

GET

/bill

Live bill for the current month.

GET

/bill/upcoming

Estimate for next month. Marked is_estimate: true.

GET

/bill/pdf

PDF of the current month’s live bill.

POST

/bills/snapshot

Save the current month’s bill as an invoice. Overwrites an existing invoice for that month.

GET

/bills

List stored invoices, newest month first.

GET

/bills/:period/pdf

PDF of a stored invoice. period is YYYY-MM.

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_pricing and upcoming_effective are both optional, but each requires the other.

  • upcoming_pricing takes the same fields as the top-level body. The example above shows only two; send all of them in a real request.

  • upcoming_effective is 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.

upcoming_effective is in the past when you save.

400

An effective date is required when upcoming pricing is set.

upcoming_pricing was sent without upcoming_effective.

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 (-1). Check the Pricing tab and the tenant’s limits.

A resource is missing from the bill

Its limit is -1, or CloudStack did not return it. Missing resources are left out without an error.

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.