## GET /api/v2/billing/unpaid-summary

**Get a summary of unpaid invoices**

Get the account's unpaid invoices in one call: the total to pay, each invoice with how soon it is due and whether the saved card will pay them automatically. Use it to decide whether to remind someone to pay. `uiShouldShow` is false when there is nothing to do, for example when the saved card will pay every invoice on its due date. `uiSuppressReason` says why. An invoice already included in a bulk-payment invoice has `isBulkPaymentChild: true` and its parent in `bulkPaymentParentId`. `count` and `totalAmount` leave those out. When the invoices cannot be read, the call still answers 200 as if nothing is unpaid (`count: 0`, `uiSuppressReason: no_unpaid_invoices`). `autoCharge.status` is `off` when the saved card or the setting cannot be read. Read the summary again before you stop reminding someone.

### Related Endpoints

- `GET /api/v2/billing/cards`: List saved cards
- `POST /api/v2/billing/cards`: Save a payment card
- `GET /api/v2/billing/account`: Get billing account

### Headers

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

### Request Example

```bash
curl "https://cloud.hostup.se/api/v2/billing/unpaid-summary" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"
```

### Response Schema

- `totalAmount` (number, required): Total left to pay on the unpaid invoices.
- `currencyCode` (string, required): Currency of `totalAmount`.
- `count` (integer, required): Number of unpaid invoices, not counting those inside a bulk-payment invoice.
- `uiDisplayKind` (string, required): The most urgent due state among the invoices. `none` when nothing is unpaid.
  Allowed values: overdue, dueSoon, upcoming, none
- `uiShouldShow` (boolean, required): True when a payment reminder is useful.
- `uiSuppressReason` (string, required, nullable): Why no reminder is needed: `no_unpaid_invoices` or `auto_charge_handles_upcoming`.
  Allowed values: no_unpaid_invoices, auto_charge_handles_upcoming
- `invoices` (array<object>, required): The unpaid invoices, earliest due date first.
- `invoices[].id` (string, optional): The invoice ID (`inv_…`).
- `invoices[].number` (string, optional, nullable): Invoice number.
- `invoices[].amount` (number, optional): Amount left to pay on this invoice, not its total.
- `invoices[].currencyCode` (string, optional): Currency of `amount`.
- `invoices[].dueAt` (string, optional, nullable): Due date. Null when unknown.
- `invoices[].dueStatus` (string, optional): `overdue`: past the due date. `dueSoon`: due today or within 7 days. `upcoming`: due later. `unknown`: no due date.
  Allowed values: overdue, dueSoon, upcoming, unknown
- `invoices[].daysOverdue` (number, optional, nullable): Days past the due date when `overdue`.
- `invoices[].daysUntilDue` (number, optional, nullable): Days until the due date when `dueSoon` or `upcoming`.
- `invoices[].isBulkPaymentChild` (boolean, optional): True when the invoice is paid through a bulk-payment invoice.
- `invoices[].bulkPaymentParentId` (string, optional, nullable): The bulk-payment invoice that includes this one.
- `autoCharge` (object, required): Always present. Whether the saved card will pay unpaid invoices automatically. Also says whether the last automatic charge went through.
- `autoCharge.enabled` (boolean, required): True when automatic card payment is on and a card is saved.
- `autoCharge.method` (object, required, nullable): The card that will be charged. Null when automatic payment is off or no card is saved.
- `autoCharge.scheduledAt` (string, required, nullable): When the next automatic charge runs: 20:00 Europe/Stockholm time on the earliest due date. After a failed charge, a daily retry for up to three days after the due date. Null when no further charge is expected.
- `autoCharge.status` (string, required): `off`: automatic card payment is off or no card is saved. `scheduled`: the card will be charged on the earliest due date. `failed`: an invoice is past due although automatic payment was on. The charge did not go through. Example: `scheduled`
  Allowed values: off, scheduled, failed
- `autoCharge.reason` (string, required, nullable): When `status` is `failed`: what went wrong with the card, whether a retry is still coming and what to do. Null otherwise. Example: `null`
- `autoCharge.lastAttemptAt` (string, required, nullable): When the last failed charge was tried. Null when no attempt was recorded or `status` is not `failed`. Example: `null`
- `autoCharge.failureKind` (string, required, nullable): Why the card was refused when `status` is `failed`. `unknown` when only the overdue invoice shows the failure. Null otherwise. Example: `null`
  Allowed values: card_declined, insufficient_funds, card_expired, authentication_required, unknown

### Responses

#### 200 - Unpaid invoices and the automatic card payment state.
```json
{
  "totalAmount": 97.5,
  "currencyCode": "SEK",
  "count": 1,
  "uiDisplayKind": "dueSoon",
  "uiShouldShow": false,
  "uiSuppressReason": "auto_charge_handles_upcoming",
  "invoices": [
    {
      "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "number": "202600001",
      "amount": 97.5,
      "currencyCode": "SEK",
      "dueAt": "2026-05-22T00:00:00.000Z",
      "dueStatus": "dueSoon",
      "daysOverdue": null,
      "daysUntilDue": 5,
      "isBulkPaymentChild": false,
      "bulkPaymentParentId": null
    }
  ],
  "autoCharge": {
    "enabled": true,
    "method": {
      "kind": "card",
      "last4": "8127",
      "brand": "visa"
    },
    "scheduledAt": "2026-05-22T18:00:00.000Z",
    "status": "scheduled",
    "reason": null,
    "lastAttemptAt": null,
    "failureKind": null
  }
}
```

#### 400 - Invalid request. The response body is an RFC 7807 Problem Details document.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request is invalid.",
  "code": "invalid_request",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - `forbidden`: the API key lacks `read:billing`. `requiredScopes` names it. The same code comes back when the account is not active.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This endpoint requires an API key with the `read:billing` scope. Broader service keys also work. Update your key's permissions in the dashboard.",
  "code": "forbidden",
  "instance": "/api/v2/billing/unpaid-summary",
  "requiredScopes": [
    "read:billing"
  ]
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller.
```json
{
  "type": "https://developer.hostup.se/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 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"
}
```
