Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Get a summary of unpaid invoices

GET /api/v2/billing/unpaid-summary

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.

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

Example

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

Responses

200 Unpaid invoices and the automatic card payment state.

Response 200
{
  "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
  }
}
Response fields
totalAmountnumber
Total left to pay on the unpaid invoices.
currencyCodestring
Currency of totalAmount.
countinteger
Number of unpaid invoices, not counting those inside a bulk-payment invoice.
uiDisplayKindstring
The most urgent due state among the invoices. none when nothing is unpaid. One of overdue, dueSoon, upcoming, none.
uiShouldShowboolean
True when a payment reminder is useful.
uiSuppressReasonstring or null
Why no reminder is needed: no_unpaid_invoices or auto_charge_handles_upcoming. One of no_unpaid_invoices, auto_charge_handles_upcoming.
invoicesarray of object
The unpaid invoices, earliest due date first.
idstring
The invoice ID (inv_…).
numberstring or null
Invoice number.
amountnumber
Amount left to pay on this invoice, not its total.
currencyCodestring
Currency of amount.
dueAtstring or null
Due date. Null when unknown.
dueStatusstring
overdue: past the due date. dueSoon: due today or within 7 days. upcoming: due later. unknown: no due date. One of overdue, dueSoon, upcoming, unknown.
daysOverduenumber or null
Days past the due date when overdue.
daysUntilDuenumber or null
Days until the due date when dueSoon or upcoming.
isBulkPaymentChildboolean
True when the invoice is paid through a bulk-payment invoice.
bulkPaymentParentIdstring or null
The bulk-payment invoice that includes this one.
autoChargeobject
Always present. Whether the saved card will pay unpaid invoices automatically. Also says whether the last automatic charge went through.
enabledboolean
True when automatic card payment is on and a card is saved.
methodobject or null
The card that will be charged. Null when automatic payment is off or no card is saved.
scheduledAtstring or null
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.
statusstring
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. One of off, scheduled, failed.
reasonstring or null
When status is failed: what went wrong with the card, whether a retry is still coming and what to do. Null otherwise.
lastAttemptAtstring or null
When the last failed charge was tried. Null when no attempt was recorded or status is not failed.
failureKindstring or null
Why the card was refused when status is failed. unknown when only the overdue invoice shows the failure. Null otherwise. One of card_declined, insufficient_funds, card_expired, authentication_required, unknown.

Errors

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

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403forbidden: the API key lacks read:billing. requiredScopes names it. The same code comes back when the account is not active.
404Not found. The resource does not exist or is not owned by the caller.
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.

This page as MarkdownOpenAPI spec