Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Get paid-through dates for VPS

GET /api/v2/vps/paid-periods

Returns the last paid day of up to 100 VPS in one call. Use it to check that a payment has been registered. Send the VPS IDs from GET /api/v2/vps in ids. Every VPS must be on your account. paidThroughDate is the last day that is paid, counted in Swedish time (Europe/Stockholm). status is refreshing while a recent payment or change is still being checked. Read again after a short wait. needs_review and unavailable mean the date could not be confirmed, not that the VPS is unpaid. The call only reads. It changes nothing on the VPS or its invoices.

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

Request

Query parameters

idsstringrequired
Comma-separated VPS IDs (vps_…), 1 to 100. Duplicates count once.

Example

GET /api/v2/vps/paid-periods
curl "https://cloud.hostup.se/api/v2/vps/paid-periods?ids=vps_01hxa3b4c5d6e7f8g9h0j1k2m3%2Cvps_01hxa3b4c5d6e7f8g9h0j1k2m4" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The paid period of each VPS, in the order of ids.

Response 200
{
  "results": [
    {
      "vpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "paidPeriod": {
        "revision": 17,
        "refreshRevision": 3,
        "status": "verified",
        "paidThroughDate": "2026-09-30",
        "outstandingInvoiceDueDate": null,
        "observedAt": "2026-09-06T12:00:00Z",
        "sourceInvoiceNumbers": [
          "202600001"
        ]
      }
    }
  ]
}
Response fields
resultsarray of object
One entry per VPS ID.
vpsIdstring
The VPS ID.
paidPeriodobject
What is paid for the VPS.
entitledThroughDatestring or null
The last day of extra coverage granted on top of what was paid. Show it as “covered through”, not “paid through”. Null when there is none.
reviewHandledboolean
True when Hostup has already handled a needs_review status with a coverage decision. It does not mark any invoice paid or remove one.
decisionRevisioninteger
Version of the coverage decision, counted apart from revision. A higher value is newer. At least 0.
revisioninteger
Version of the paid period. A higher value is newer. At least 0.
refreshRevisioninteger
Refresh round of the paid period. When you merge two reads, compare it before revision. At least 0.
statusstring
verified: paidThroughDate is confirmed. Show it. refreshing: the period is being read again. paidThroughDate is the last confirmed date, or null. needs_review: the period could not be confirmed automatically and Hostup checks it. Do not show a date. unavailable: no paid period can be shown now. One of verified, refreshing, needs_review, unavailable.
paidThroughDatestring or null
The last paid day, inclusive, in Swedish time (Europe/Stockholm). It is not an invoice due date or a suspension date.
outstandingInvoiceDueDatestring or null
sourceInvoiceNumbersarray of string
observedAtstring or null

Errors

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

400ids is missing, has more than 100 IDs or holds a value that is not a VPS ID. Another query parameter also returns this. code is invalid_request.
401No valid API key or session.
403The key lacks a required scope.
404One of the IDs is not a VPS on your account. code is vps_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.
503Paid periods could not be read right now. code is service_billing_unavailable. Try again later.

This page as MarkdownOpenAPI spec