List invoices
GET /api/v2/billing/invoices
List the invoices on the account, one page at a time. Narrow the list with status, searchQuery or the issue and due dates. Pass nextCursor as cursor to get the next page. A page can hold fewer invoices than limit, even none, while hasMore is still true. Drafts are left out unless you ask for status=draft. Each invoice has its amounts in totals, the actions you can take in actions and the ways it can be paid in paymentMethods. List items are summaries. They have no lineItems, payments, note, overpaymentCredit, renewalInvoicing or cancellation. Read those with GET /api/v2/billing/invoices/{id}.
Authentication: An API key with the scope read:billing. About keys and scopes
Request
Query parameters
limitinteger20. 1 to 100.cursorstringnextCursor value from the previous page.statusstringunpaid includes overdue invoices but not invoices in debt collection. overdue: unpaid and past the due date. collections: handed to debt collection. Invoices found with overdue or collections come back with status: unpaid. partially_paid invoices have actions.canPay.allowed: false and cannot be paid through the API. One of draft, unpaid, overdue, paid, partially_paid, cancelled, refunded, collections.searchQuerystring_ and - only. A short part can return only some of the matches, so search for the full number to find one invoice.datestringYYYY-MM-DD. Set dateOp to compare.dateOpstringdate is compared: lt, lte, eq, gte or gt. One of lt, gt, lte, gte, eq.duedatestringYYYY-MM-DD. Set duedateOp to compare. Ignored with status=overdue.duedateOpstringduedate is compared: lt, lte, eq, gte or gt. Ignored with status=overdue. One of lt, gt, lte, gte, eq.skipCacheinteger1 to read the list fresh instead of from cache. The list is cached for up to a minute. One of 1.Example
curl "https://cloud.hostup.se/api/v2/billing/invoices" \ -H "Authorization: Bearer $HOSTUP_API_KEY"Responses
200 One page of invoices. Each item is a summary of the invoice.
{ "data": [ { "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3", "number": "202600001", "status": "paid", "dates": { "issuedAt": "2026-04-27T12:00:00.000Z", "dueAt": "2026-05-11T23:59:59.000Z", "paidAt": "2026-04-27T12:34:56.000Z" }, "totals": { "currencyCode": "SEK", "subtotal": 199, "taxAmount": 49.75, "taxRateDecimal": 0.25, "creditApplied": 0, "total": 248.75, "amountPaid": 248.75, "amountRefunded": 0, "outstanding": 0 }, "actions": { "canPay": { "allowed": false, "reason": "Invoice is already paid." }, "canGeneratePaymentLink": { "allowed": false, "reason": "Invoice is already paid." }, "canBulkPay": { "allowed": false, "reason": "Invoice is already paid." }, "canCancel": { "allowed": false, "reason": "Only unpaid invoices can be cancelled.", "code": "invoice_not_unpaid" }, "canEmail": { "allowed": true, "reason": null }, "canDownload": { "allowed": true, "reason": null }, "canReissueInCurrency": { "allowed": false, "reason": "Swedish billing accounts pay SEK invoices by bankgiro, Swish or card.", "code": "account_country_not_eligible" } }, "paymentMethods": { "card": { "method": "card", "label": "Card", "available": false, "reason": "Invoice is already paid.", "checkoutMode": "payment", "requirements": { "minimumAmount": { "amount": 3, "currencyCode": "SEK", "comparison": "greater_than" } } }, "accountCredit": { "method": "accountCredit", "label": "Account credit", "available": false, "reason": "Invoice is already paid.", "checkoutMode": null, "requirements": { "invoiceCurrencyCode": "SEK", "accountCurrencyCode": "SEK", "availableBalance": { "amount": 0, "currencyCode": "SEK" }, "maximumAmount": { "amount": 0, "currencyCode": "SEK", "comparison": "less_than_or_equal" } } }, "swish": { "method": "swish", "label": "Swish", "available": false, "reason": "Invoice is already paid.", "checkoutMode": null, "requirements": { "invoiceCurrencyCode": "SEK", "accountCountryCode": "SE" } }, "bankgiro": { "method": "bankgiro", "label": "Bankgiro", "available": false, "reason": "Invoice is already paid.", "checkoutMode": null, "requirements": { "invoiceCurrencyCode": "SEK", "accountCountryCode": "SE" } }, "sepa": { "method": "sepa", "label": "SEPA bank transfer", "available": false, "reason": "Invoice is already paid.", "checkoutMode": "sepa_bank_transfer_payment", "requirements": { "invoiceCurrencyCode": "EUR" } }, "alipay": { "method": "alipay", "label": "Alipay", "available": false, "reason": "Invoice is already paid.", "checkoutMode": "alipay_payment", "requirements": { "invoiceCurrencyCodes": [ "EUR", "USD" ] } }, "crypto": { "method": "crypto", "label": "Cryptocurrency", "available": false, "reason": "Cryptocurrency payments are not available for Swedish billing accounts.", "checkoutMode": null, "requirements": { "invoiceCurrencyCodes": [ "SEK", "EUR", "USD" ], "accountCountryExcludedCode": "SE", "accountType": "private", "requiresCardVerification": true }, "visible": false } }, "paymentLinkGeneratorUrl": null, "isBulkPaymentChild": false, "bulkPaymentParentId": null } ], "hasMore": false, "nextCursor": null}Response fields
dataarray of objectidstringorderIdstringord_…) when the invoice belongs to an order. A domain renewal invoice whose order is still open is cancelled by cancelling that order first.numberstringstatusstringdraft, unpaid, partially_paid, paid, cancelled, refunded.datesobjectissuedAtstringdueAtstringpaidAtstringtotalsobjectcurrencyCodestringsubtotalnumbertaxAmountnumbertaxRateDecimalnumbercreditAppliednumbertotalnumberamountPaidnumberamountRefundednumberoutstandingnumberlineItemCountintegerlineItemsarray of objectkindstringvps, shared_hosting, domain, addon, credit, setup, other.purposestringrenewal, registration, transfer, account_credit_top_up, credit, setup.resourceobjecttypestringvps, shared_hosting, domain.idstring or nulldisplayNamestring or nullproductNamestringconfigurableOptionsarray of objectkey is the label in lower case with the bracket part dropped and other characters turned into _.keystringlabelstringvaluestringdescriptionstringdisplayDescriptionstringdisplaySecondaryLinesarray of stringdisplayDescription, such as the period.monthlyHintstringdetailsHintstringquantitynumberunitAmountnumbertotalAmountnumbercurrencyCodestringperiodobjectstartAtstringendAtstringoverpaymentCreditobjectdecisionstringcard_bankgiro_overpayment_already_credited.currencyCodestringSEK.invoiceAmountnumberexcessAmountnumbercreditedAtstringcurrentCreditBalancenumberpaymentsarray of objectkindstring or nullpayment: a payment of the invoice. account_credit_added: an overpayment added to account credit, not counted as a payment. refund: money returned (see refundedTo). rounding: a remainder under 1 SEK that Hostup wrote off so the invoice counts as paid. It is not money the customer paid. It is never a refund or a credit movement. One of payment, account_credit_added, refund, rounding.methodstring or nullmethodLabel for the text to show. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto, paypal, invoice, rounding, other.methodLabelstring or nullamountnumbercurrencyCodestringamount.refundedbooleanrefund row says where the money went.refundedTostringaccountCredit: the money is on the account balance and pays the next invoice automatically. paymentMethod: returned to the payment method. unknown: not recorded. One of accountCredit, paymentMethod, unknown.atstringnotestringactionsobjectcanPayobjectallowedbooleanreasonstring or nullcodestring or nullcanGeneratePaymentLinkobjectallowedbooleanreasonstring or nullcodestring or nullcanBulkPayobjectallowedbooleanreasonstring or nullcodestring or nullcanCancelobjectallowedbooleanreasonstring or nullcodestring or nullcanEmailobjectallowedbooleanreasonstring or nullcodestring or nullcanDownloadobjectallowedbooleanreasonstring or nullcodestring or nullcanReissueInCurrencyobjectPOST /api/v2/billing/invoices/{id}/actions/reissue-in-currency. When it is blocked, branch on code: invoice_order_backed (a pending order or plan change backs the invoice: cancel that order, change currency, then order again), invoice_domain_renewal (cancel the renewal order, then renew again), invoice_partially_settled, invoice_multiple_services, invoice_usage_not_reissuable and renewal_period_ended (contact support), account_country_not_eligible (Swedish accounts pay by bankgiro, Swish or card).allowedbooleanreasonstring or nullcodestring or nullpaymentMethodsobjectcard, accountCredit, swish, bankgiro, sepa, alipay and crypto. Check them before you start a payment.cardobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.accountCreditobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.swishobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.bankgiroobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.sepaobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.alipayobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.cryptoobjectmethodstringpaymentMethods. Card checkout and wallets are all card. One of card, accountCredit, swish, bankgiro, sepa, alipay, crypto.labelstringavailablebooleanvisiblebooleanreasonstring or nullavailable is false.checkoutModestring or nullpayment, sepa_bank_transfer_payment, alipay_payment.requirementsobjectinvoiceCurrencyCodestringinvoiceCurrencyCodesarray of stringaccountCountryCodestringaccountCountryExcludedCodestringaccountTypestringprivate, organisation.accountCurrencyCodestringrequiresCardVerificationbooleanavailableBalanceobjectamountnumbercurrencyCodestringminimumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.maximumAmountobjectamountnumbercurrencyCodestringcomparisonstringamount. greater_than: more than it, used in minimumAmount. less_than_or_equal: at most it, used in maximumAmount. One of greater_than, less_than_or_equal.paymentLinkGeneratorUrlstring or nullPOST /api/v2/billing/invoices/{id}/actions/generate-payment-link). Null when actions.canGeneratePaymentLink.allowed is false.isBulkPaymentChildbooleanbulkPaymentParentId instead. actions.canPay can still be allowed on such an invoice.bulkPaymentParentIdstring or nullisBulkPaymentChild is false.coversInvoiceIdsarray of stringrenewalInvoicingobjectpreferencestringconsolidated, separate.generatedByAutomationbooleanisConsolidatedbooleanlabelstringsettingsUrlstringdeliveryobjectchannelstringpeppol.statusstringqueued: accepted for sending and waiting, for example for the send window. An unpaid invoice from today for an organisation registered in Peppol is also queued until it is sent. sent: sent into the Peppol network. delivered: the recipient’s access point confirmed receipt. A failed or ineligible delivery never shows here. Such an invoice has no delivery field. One of queued, sent, delivered.sentAtstring or nulldeliveredAtstring or nullcancellationobjectcodestringdomain_registered_elsewhere: an unpaid order for a new domain registration was cancelled automatically. Someone else registered the name before the invoice was paid. A new domain is registered only once its invoice is paid. The name was never on this account and nothing was charged. One of domain_registered_elsewhere.reasonstringcode to branch or to pick a translated text.domainNamestringregistrarNamestring or nullnull when unknown.registeredAtstring or nullnull when unknown.cancelledAtstring or nullregisteredAt, since the cancellation follows that registration.hasMorebooleannextCursorstring or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_request: a query parameter is wrong. For example limit is outside 1 to 100, cursor is not one this endpoint returned, status is not a listed value, or a date is not YYYY-MM-DD. detail says which. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden: the API key lacks read:billing. requiredScopes names it. The same code comes back when the account is not active. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |