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
idstringrequireddom_…).Example
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.
{ "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
domainIdstringrenewalScheduledbooleantrue.newExpiresAtstring or nullbillingobjectamountnumber or nullcurrencyCodestringbillingCyclestringrenewsForobjectbillingCyclestringannually.monthsintegerorderIdstring or nullrenewalInvoicenullinvoiceLookupPendingbooleanErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is domain_not_found. |
| 409 | The 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. |
| 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. |
| 502 | Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists. |