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
idstringrequiredPublic invoice ID from
GET /api/v2/billing/invoices (inv_…).Example
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."}{ "available": false, "reason": "This invoice has no pay-as-you-go usage line items to attribute."}Response fields
availablebooleanOne of
true.periodobjectstartAtstringendAtstringcoveragestringOne of
full, partial, none.currencyCodestringamountsExclVatbooleanAlways true. Every amount here excludes VAT. One of
true.attributedAmountnumberThe amount divided between servers, excl. VAT. The servers’
estimatedAmount values add up to it.resourcesarray of objectOne row per resource on the invoice, largest amount first. Taken from the invoice lines. Filled whatever the
coverage.keystringThe resource.
bandwidth is data transfer. One of cpu, memory, storage, ipv4, bandwidth.amountnumberAmount billed for this resource, excl. VAT.
quantityHoursnumberMetered hours: core-hours, GB-hours or address-hours. Not on
bandwidth rows.quantityGbnumberMetered data transfer in GB. Only on
bandwidth rows.ipCountApproxnumberipv4 rows: about how many extra addresses were billed at once.ipDaysApproxnumberipv4 rows: about how many days each address was held.averageCoresApproxnumbercpu rows: average cores over the period.averageGbApproxnumbermemory and storage rows: average GB over the period.vmsarray of objectThe Cloud VPS servers that used resources in the period, including deleted ones.
idstring or nullThe VPS ID (
vps_…).namestring or nullHostname of the server.
displayNamestringThe name given to the server in the client area, when set.
firstObservedAtstringFirst day in the period with recorded usage.
lastObservedAtstringLast day in the period with recorded usage.
latestObservedAtstringLast day with recorded usage at all, also after the period.
usageobjectUsage recorded in the period.
cpuCoreHoursnumberramGbHoursnumberdiskGbHoursnumberbandwidthGbnumberipHoursnumberestimatedAmountnumberThis server’s share of
attributedAmount, excl. VAT.unattributedAmountnumberAmount not tied to one server, excl. VAT. For example object storage, the mail relay or usage outside the recorded days.
unattributedNotestringExplains
unattributedAmount.notestringExplains a
partial or none coverage.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is invoice_not_found. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |