## GET /api/v2/vps/paid-periods

**Get paid-through dates for VPS**

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.

### Related Endpoints

- `GET /api/v2/vps`: List VPS instances
- `GET /api/v2/vps/{id}`: Get a VPS
- `GET /api/v2/vps/metrics`: List CPU and memory use of all VPS

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scope: `read:vm`

### Parameters

- `ids` (query, string, required): Comma-separated VPS IDs (`vps_…`), 1 to 100. Duplicates count once. Example: `vps_01hxa3b4c5d6e7f8g9h0j1k2m3,vps_01hxa3b4c5d6e7f8g9h0j1k2m4`

### Request Example

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

### Response Schema

- `results` (array<object>, required): One entry per VPS ID.
- `results[].vpsId` (string, required): The VPS ID. Example: `vps_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `results[].paidPeriod` (object, required): What is paid for the VPS.
- `results[].paidPeriod.entitledThroughDate` (string, optional, nullable): 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.
- `results[].paidPeriod.reviewHandled` (boolean, optional): True when Hostup has already handled a `needs_review` status with a coverage decision. It does not mark any invoice paid or remove one.
- `results[].paidPeriod.decisionRevision` (integer, optional): Version of the coverage decision, counted apart from `revision`. A higher value is newer.
- `results[].paidPeriod.revision` (integer, required): Version of the paid period. A higher value is newer.
- `results[].paidPeriod.refreshRevision` (integer, required): Refresh round of the paid period. When you merge two reads, compare it before `revision`.
- `results[].paidPeriod.status` (string, required): `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.
  Allowed values: verified, refreshing, needs_review, unavailable
- `results[].paidPeriod.paidThroughDate` (string, required, nullable): The last paid day, inclusive, in Swedish time (Europe/Stockholm). It is not an invoice due date or a suspension date.
- `results[].paidPeriod.outstandingInvoiceDueDate` (string, required, nullable)
- `results[].paidPeriod.sourceInvoiceNumbers` (array<string>, required)
- `results[].paidPeriod.observedAt` (string, required, nullable)

### Responses

#### 200 - The paid period of each VPS, in the order of `ids`.
```json
{
  "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"
        ]
      }
    }
  ]
}
```

#### 400 - `ids` 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`.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid VPS identifiers",
  "status": 400,
  "detail": "Provide 1–100 public VPS IDs in ids.",
  "code": "invalid_request",
  "instance": "/api/v2/vps/paid-periods",
  "errors": [
    {
      "pointer": "/ids",
      "code": "invalid_request",
      "detail": "Provide 1–100 public VPS IDs."
    }
  ]
}
```

#### 401 - No valid API key or session.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Validation failed",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z",
  "errors": [
    {
      "pointer": "/name",
      "detail": "`name` is required.",
      "code": "invalid_request"
    }
  ]
}
```

#### 403 - The key lacks a required scope.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Validation failed",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z",
  "errors": [
    {
      "pointer": "/name",
      "detail": "`name` is required.",
      "code": "invalid_request"
    }
  ]
}
```

#### 404 - One of the IDs is not a VPS on your account. `code` is `vps_not_found`.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Validation failed",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z",
  "errors": [
    {
      "pointer": "/name",
      "detail": "`name` is required.",
      "code": "invalid_request"
    }
  ]
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 503 - Paid periods could not be read right now. `code` is `service_billing_unavailable`. Try again later.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Validation failed",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z",
  "errors": [
    {
      "pointer": "/name",
      "detail": "`name` is required.",
      "code": "invalid_request"
    }
  ]
}
```
