Skip to content

Break down a Cloud VPS usage invoice

GET /api/v2/billing/invoices/{id}/payg-breakdown

Split a Cloud VPS usage invoice by server, including servers deleted since. Cloud VPS usage is billed for the whole account. The invoice lines do not name servers. This route divides each resource’s amount by the usage recorded for each server. resources explains the invoice per resource: extra IPv4 addresses, CPU, memory, storage and data transfer. coverage says how much of the period has per-server records. All amounts exclude VAT. An invoice without Cloud VPS usage returns available: false.

Authentication: An API key with the scope read:billing. About keys and scopes

Request

Path parameters

idstringrequired
Public invoice ID from GET /api/v2/billing/invoices (inv_…).

Example

GET /api/v2/billing/invoices/{id}/payg-breakdown
curl "https://cloud.hostup.se/api/v2/billing/invoices/inv_01hxa3b4c5d6e7f8g9h0j1k2m3/payg-breakdown" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The breakdown. available: false when the invoice has no Cloud VPS usage.

{
"available": true,
"period": {
"startAt": "2026-05-31T16:00:03.000Z",
"endAt": "2026-06-30T00:00:00.000Z"
},
"coverage": "full",
"currencyCode": "SEK",
"amountsExclVat": true,
"attributedAmount": 118.17,
"resources": [
{
"key": "ipv4",
"amount": 13.21,
"quantityHours": 440.5,
"quantityGb": 82.4,
"ipCountApprox": 1,
"ipDaysApprox": 18,
"averageCoresApprox": 3.5,
"averageGbApprox": 8.2
}
],
"vms": [
{
"id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "web1.example.com",
"displayName": "Web server",
"firstObservedAt": "2026-05-31T00:00:00.000Z",
"lastObservedAt": "2026-06-30T00:00:00.000Z",
"latestObservedAt": "2026-07-06T00:00:00.000Z",
"usage": {
"cpuCoreHours": 1394,
"ramGbHours": 2788,
"diskGbHours": 34850,
"bandwidthGb": 82.4,
"ipHours": 697
},
"estimatedAmount": 64.2
}
],
"unattributedAmount": 12.5,
"unattributedNote": "Part of this invoice is metered usage that cannot be tied to a specific VM (e.g. object storage, mail relay, or usage outside the recorded window).",
"note": "Per-VM usage recording covers only part of this invoice period, so per-VM amounts are a lower bound for the covered days."
}
Response fields
availableboolean
One of true.
periodobject
startAtstring
endAtstring
coveragestring
One of full, partial, none.
currencyCodestring
amountsExclVatboolean
Always true. Every amount here excludes VAT. One of true.
attributedAmountnumber
The amount divided between servers, excl. VAT. The servers’ estimatedAmount values add up to it.
resourcesarray of object
One row per resource on the invoice, largest amount first. Taken from the invoice lines. Filled whatever the coverage.
keystring
The resource. bandwidth is data transfer. One of cpu, memory, storage, ipv4, bandwidth.
amountnumber
Amount billed for this resource, excl. VAT.
quantityHoursnumber
Metered hours: core-hours, GB-hours or address-hours. Not on bandwidth rows.
quantityGbnumber
Metered data transfer in GB. Only on bandwidth rows.
ipCountApproxnumber
ipv4 rows: about how many extra addresses were billed at once.
ipDaysApproxnumber
ipv4 rows: about how many days each address was held.
averageCoresApproxnumber
cpu rows: average cores over the period.
averageGbApproxnumber
memory and storage rows: average GB over the period.
vmsarray of object
The Cloud VPS servers that used resources in the period, including deleted ones.
idstring or null
The VPS ID (vps_…).
namestring or null
Hostname of the server.
displayNamestring
The name given to the server in the client area, when set.
firstObservedAtstring
First day in the period with recorded usage.
lastObservedAtstring
Last day in the period with recorded usage.
latestObservedAtstring
Last day with recorded usage at all, also after the period.
usageobject
Usage recorded in the period.
cpuCoreHoursnumber
ramGbHoursnumber
diskGbHoursnumber
bandwidthGbnumber
ipHoursnumber
estimatedAmountnumber
This server’s share of attributedAmount, excl. VAT.
unattributedAmountnumber
Amount not tied to one server, excl. VAT. For example object storage, the mail relay or usage outside the recorded days.
unattributedNotestring
Explains unattributedAmount.
notestring
Explains a partial or none coverage.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is invoice_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.