Renew an owned domain with POST /v2/domains/{domainId}/renew. The request uses the current domain identifier, a supported period and the relevant price quote. It is a paid domain operation, so retain its original business reference when handling retries.
IN THIS ARTICLE
01 Check the domain first
- List or search your domains and select the exact returned domain identifier.
- Read its current status and expiry. If your stored information is old, use the supported synchronization workflow.
- Check that the TLD permits renewal for the desired number of years and that the domain is in a renewable state. Redemption restoration is a separate operation.
- Obtain the current renewal quote and confirm the funding available for the account's payment policy.
02 Submit the renewal
Use domains:renew permission and the authentication helper in the API introduction. Replace the example identifiers with values returned for your account.
POST /v2/domains/DOMAIN_ID/renew
Idempotency-Key: renewal-local-order-1042
Content-Type: application/json
{
"years": 1,
"price_quote_id": "QUOTE_ID",
"client_reference": "local-order-1042"
}The current period field is years. Do not reuse old regperiod or addon arrays from the retired integration. Include any additional fields only as required by the current operation contract.
03 Confirm the result
Store the returned operation and job references. A queued or accepted response does not establish that the registrar extended the expiry. Follow the operation, then reread the domain and confirm the resulting expiry and financial settlement.
Keep registry expiry separate from your customer's invoice due date. A paid retail invoice alone does not prove that the upstream renewal succeeded.
Should I submit another renewal after an API timeout?
Do not send a new renewal simply because the connection closed. Inspect the original operation and provider status. If the request is eligible for a retry, use the supported operation-retry workflow or resend the unchanged request with its original idempotency key.
If the domain needs restoration, a different period or a revised quote, review that new business action explicitly. An extra year added accidentally may not be reversible through a normal refund. For unresolved cases, provide support with the domain, pre-request expiry, quote and operation references.