Skip to content

Renew a domain

POST /api/v2/domains/{id}/actions/renew

Create a renewal order and invoice for a domain now. Check actions.canRenewNow on GET /api/v2/domains/{id}/renewal first. The renewal length is the domain’s billing period. To change it, use POST /api/v2/domains/{id}/billing-cycle before you renew. Send no body or an empty object. The response carries the new order and the invoice to pay. The domain is renewed at the registry once the invoice is paid. Until then newExpiresAt is null. When a renewal order already exists, the call returns 409 existing_invoice_blocking with its invoice in existingInvoice and creates nothing new. Contacts on the account need permission to place orders.

Authentication: An API key with the scopes write:domains and write:billing. About keys and scopes

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Example

POST /api/v2/domains/{id}/actions/renew
curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/renew" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json"

Responses

200 The renewal order and its invoice were created.

Response 200
{
"domainId": "dom_01hxa3b4c5d6e7f8g9h0j1k2m3",
"renewalScheduled": true,
"newExpiresAt": null,
"billing": {
"amount": 159,
"currencyCode": "SEK",
"billingCycle": "annually"
},
"renewsFor": {
"billingCycle": "annually",
"months": 12
},
"orderId": "ord_01hxa3b4c5d6e7f8g9h0j1k2m3",
"renewalInvoice": {
"id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"number": "202600001",
"amount": 198.75,
"currencyCode": "SEK",
"dueAt": "2026-05-11T23:59:59.000Z",
"status": "unpaid",
"paymentUrl": "/billing?invoice=202600001"
}
}
Response fields
domainIdstring
renewalScheduledboolean
One of true.
newExpiresAtstring or null
billingobject
amountnumber or null
currencyCodestring
billingCyclestring
renewsForobject
billingCyclestring
One of annually.
monthsinteger
orderIdstring or null
renewalInvoicenull
invoiceLookupPendingboolean
Present only when the renewal order went through but its invoice was still being created.

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.
409The domain cannot be renewed now. existing_invoice_blocking: a renewal order already exists; pay the invoice in existingInvoice. domain_not_renewable: the domain’s state or registry blocks a renewal; errors[0].code and detail say why. renewal_in_progress: another action is changing the domain; try again in a moment.
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.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.