Skip to content

Knowledgebase

Request registry deletion without confusing it with DNS-zone removal

domain-nexus, development

The registry deletion endpoint requests removal of a registered domain where the registry and upstream provider permit it. It is a consequential lifecycle action. Use it only for an explicitly authorised domain retirement, not to remove a DNS zone, hide a local list entry or cancel a hosting invoice.

01 Confirm the intended action

Method Resource Scope Idempotency-Key
POST /v2/domains/{domainId}/request-delete domains:delete Required
  1. Read the exact owned domain using its returned public ID and confirm its spelling with the account owner.
  2. Review the provider's supported deletion behaviour, lifecycle timing and any restrictions. Do not assume deletion means the name will become immediately available.
  3. Inventory dependent website, email, verification and nameserver services. Retain required records and exports before retirement.
  4. Check linked orders, pending operations and any billing decision separately.
  5. Submit the delete request with a clear reason and the required idempotency key only after the owner has approved this registry action.
  6. Track the returned domain operation and reconcile the final registrar state. Keep the audit reference with the retirement record.

Will this remove a DNS zone or refund the purchase?

Those are separate workflows. A registration deletion request does not establish that a provider's DNS zone has been removed, that all hosted services have ended or that a refund is approved. Review each dependent service deliberately.

What if the provider refuses deletion?

Preserve the reason and current domain state. Some registries or lifecycle states do not expose this action through the provider. Do not edit the module database to mark the domain deleted or repeatedly submit a new request to force a different outcome.

If the response is uncertain, inspect the existing operation before any retry. Once provider work completes, recreating a local record cannot reverse the registry's action. A rollback plan must reflect the registry's actual recovery rules rather than a database restoration alone.

For a customer who only wants to stop using a website, consider whether changing or removing the relevant hosting/DNS service is the actual requested task before reaching for a registration deletion operation.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support