Skip to content

Get domain renewal status

GET /api/v2/domains/{id}/renewal

Shows the renewal state of a domain: an open renewal order and its invoice, auto-renew, days until expiry and whether it can be renewed now. Check actions.canRenewNow.allowed before you call POST /api/v2/domains/{id}/actions/renew. The gate already includes the registry’s renewal window. When hasPendingOrder is true, a renewal order is open. Pay it at renewalInvoice.paymentUrl. To decline it, call POST /api/v2/domains/{id}/actions/respond-to-renewal with { "accept": false }.

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

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Example

GET /api/v2/domains/{id}/renewal
curl "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/renewal" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The renewal state of the domain.

Response 200
{
"hasPendingOrder": true,
"orderId": "ord_01hxa3b4c5d6e7f8g9h0j1k2m3",
"orderNumber": "1500276215",
"invoiceId": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"invoiceNumber": "202664206",
"proformaId": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"invoiceStatus": "Unpaid",
"billing": {
"amount": 7,
"currencyCode": "EUR",
"billingCycle": "annually"
},
"renewsFor": {
"billingCycle": "annually",
"months": 12
},
"createdAt": "2026-04-27T12:00:00.000Z",
"renewalInvoice": {
"id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"number": "202664206",
"amount": 7,
"currencyCode": "EUR",
"dueAt": "2026-05-11T23:59:59.000Z",
"status": "unpaid",
"paymentUrl": "/billing?invoice=202664206"
},
"otherDomainsOnOrder": [],
"autoRenew": true,
"daysUntilExpiry": 30,
"hasUpcomingRenewal": true,
"actions": {
"canEnableAutoRenew": {
"allowed": false,
"reason": "Auto-renew already enabled."
},
"canRenewNow": {
"allowed": false,
"reason": "Already renewed this period; next renewal available in 30 days."
}
}
}
Response fields
hasPendingOrderboolean
orderIdstring or null
orderNumberstring or null
invoiceIdstring or null
invoiceNumberstring or null
proformaIdstring or null
invoiceStatusstring or null
billingobject
amountnumber or null
currencyCodestring
billingCyclestring
renewsForobject
billingCyclestring
One of annually.
monthsinteger
createdAtstring or null
renewalInvoicenull
autoRenewboolean or null
daysUntilExpiryinteger or null
hasUpcomingRenewalboolean
actionsobject
canEnableAutoRenewobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canRenewNowobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
optionsarray of object
Older field kept for existing integrations. Read renewsFor and billing instead.

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 caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is domain_not_found.
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.