Read verified paid periods for VPS instances

GET /api/v2/vps/paid-periods

Cheap bounded batch read for up to 100 owned public VPS IDs from GET /api/v2/vps.

Does not query hypervisors, change service dates, suspend instances or apply payments.

Poll only refreshing results with bounded backoff.

Paid-through dates are inclusive calendar dates in Europe/Stockholm.

Unknown data is not evidence of unpaid service.

Authentication and read:vm are required.

VPS Services VM

Authentication

Required API scope: read:vm

Authenticate with an API key in the Authorization: Bearer <token> header.

Context

Related endpoints

GET /api/v2/vps List VPS instances GET /api/v2/vps/{id} Get VPS details GET /api/v2/vps/metrics List live VPS metrics

Query Parameters

ids string required · Example: vps_01hxa3b4c5d6e7f8g9h0j1k2m3

Comma-separated list of 1–100 public VPS IDs.

Headers

Authorization Bearer <token>

Accept application/json

Responses

200 Paid-period evidence for every requested VPS. 1 field

results array<object> required

results[].vpsId string required

results[].paidPeriod object required

results[].paidPeriod.revision integer · min: 0 required

Monotonic source revision used to reject stale responses.

results[].paidPeriod.refreshRevision integer · min: 0 required

Refresh generation. Compare this before revision when merging concurrent reads.

results[].paidPeriod.status string · enum required

verified

refreshing

needs_review

unavailable

results[].paidPeriod.paidThroughDate string · nullable required

Inclusive last verified paid calendar day in Europe/Stockholm. Not an invoice due date or a suspension instruction.

results[].paidPeriod.outstandingInvoiceDueDate string · nullable required

Nullable: may be null when not applicable.

results[].paidPeriod.sourceInvoiceNumbers array<string> required

results[].paidPeriod.observedAt string · nullable required

Nullable: may be null when not applicable.

400 invalid_request: invalid/oversized identifiers or unknown query fields. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

401 unauthorized: authentication required. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

403 forbidden: missing read:vm scope. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

404 vps_not_found: an identifier is absent or belongs to another customer. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

429 Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

500 Internal error. Retry later or contact support if the issue persists. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

503 service_billing_unavailable: ownership inventory could not be read. 10 fields

type string · Example: https://developer.hostup.se/errors/invalid_request

title string · Example: Validation failed

status integer · Example: 400

detail string · Example: The request body failed validation.

code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders

requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3

timestamp string · Example: 2026-04-27T12:34:56.000Z

errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode

errors[].detail string required · Example: `eppCode` is required for this transfer.

errors[].code string required · Example: missing_required

extensions object

GET https://cloud.hostup.se/api/v2/vps/paid-periods

For AI assistants

View as Markdown

cURL

curl -X GET "https://cloud.hostup.se/api/v2/vps/paid-periods?ids=vps_01hxa3b4c5d6e7f8g9h0j1k2m3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
  "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"
        ]
      }
    }
  ]
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "vpsId": {
            "type": "string"
          },
          "paidPeriod": {
            "type": "object",
            "properties": {
              "revision": {
                "type": "integer",
                "description": "Monotonic source revision used to reject stale responses.",
                "minimum": 0
              },
              "refreshRevision": {
                "type": "integer",
                "description": "Refresh generation. Compare this before revision when merging concurrent reads.",
                "minimum": 0
              },
              "status": {
                "type": "string",
                "enum": [
                  "verified",
                  "refreshing",
                  "needs_review",
                  "unavailable"
                ]
              },
              "paidThroughDate": {
                "type": "string",
                "description": "Inclusive last verified paid calendar day in Europe/Stockholm. Not an invoice due date or a suspension instruction.",
                "nullable": true
              },
              "outstandingInvoiceDueDate": {
                "type": "string",
                "nullable": true
              },
              "sourceInvoiceNumbers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "observedAt": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      }
    }
  }
}