Skip to main content

​
Domain Renewals & Expiration

This guide covers how to renew domains through the Core API, what happens when a domain expires, which webhooks signal lifecycle changes, and when to use the name.com web UI for recovery after a domain leaves your API account. Timelines vary by TLD. Always confirm the Guaranteed Renewal Window length with expirationGracePeriod from the TLD requirements endpoints.

​
Renewal options (while the domain is in your account)

You have two primary options for renewing domains before they leave your account inventory.

​
1. Enable auto-renew

  • Automatically renews domains on your account’s renewal schedule
  • Timing is configurable to ~30 days before expiration or ~7 days before expiration
  • Set per domain with autorenewEnabled on Update Domain, or manage domains in the name.com portal
  • Account-wide renewal schedule settings live under payment / account settings (renewal setting and renewal schedule)

​
2. Manual renewal (API or dashboard)

  • Renew programmatically with Renew Domain, or renew in the name.com portal
  • Prefer batching renewals (for example up to ~500 at a time) and always pass idempotency keys
  • Manual renewal gives you control over exact timing
If a domain has expired but is still within the Guaranteed Renewal Window described below, renewing via Renew Domain restores the domain and records so their site can resume service. (typically ~25 days after expiration for many gTLDs; DNS and other services depend on the registry and any locks applied after expiration).
Domain renewals are non-refundable. If a customer disputes a domain renewal, advise them to disable auto-renew and let the domain expire naturally out of the account. Provide clear communication leading up to renewal so customers can make adjustments before the domain renews. You can also charge the customer first and renew slightly later if you need tighter billing control.

​
ICANN-required renewal emails

If you manage registrant communications, you are responsible for ICANN-required renewal notices (pre-expiry reminders and a post-expiry recovery notice). In addition to the ICANN-required emails, we recommend sending supplemental communications based on the renewal type, along with additional reminder emails to improve customer awareness and coverage. The ~month-before and ~week-before expiration messages are reminder communications; send order confirmation emails once renewal actually occurs. See Registrant Communications for required timing, content, and contact models.

​
Post-expiration lifecycle

If a domain is not renewed before expireDate, it moves through the stages below. Day ranges are typical for common gTLDs (for example .com); always confirm your TLD with expirationGracePeriod. Domain Name Lifecycle

​
1. Domain Expires (day 0)

  • The domain reaches its expiration date
  • DNS, website, and email may stop working depending on the registry and any post-expiration locks (see ExpirationClientHold)
  • Subscribe to domain.expiration for an informational signal that the Guaranteed Renewal Window has started — do not remove the domain from your systems yet

​
2. Guaranteed Renewal Window (days 1–25)

This is the same as the account / renewal grace period for API inventory. Length comes from expirationGracePeriod on the TLD requirements endpoints — the number of days after expiration you can renew before the domain is removed from your account.
  • Typical duration: up to ~25 days for many gTLDs (for example .com). Some TLDs are shorter — use Get TLD Requirements
  • Pricing: Standard renewal pricing applies
  • Action: Renew via Renew Domain or the name.com dashboard
This is the window where the Core API guarantees you can renew while the expired domain remains in your account.

​
3. Extended Renewal Window (days 26–43)

  • The domain leaves your API inventory: Get/List no longer return it once expirationGracePeriod has passed
  • You receive account.domain.removal with reason: expiration (if subscribed)
  • Further renewal may still be possible in the name.com Renewal Center for this limited window (typically ~days 26–43 for common gTLDs; registry and TLD-dependent)
  • Extended renewal is not guaranteed. It is available through the name.com UI only

​
4. Redemption Grace Period (days 44–74)

  • After the registry’s delete / redemption window begins, standard renewal is no longer available
  • Domains may still be recoverable via redemption (restore) in the Renewal Center
  • Redemption typically includes a redemption fee plus a renewal term; fees and availability are registry-specific
  • Redemption is not guaranteed. It is available through the name.com UI only

​
5. Pending Delete at Registry (days 75–79)

  • The domain is scheduled for final deletion at the registry
  • No recovery is possible

​
6. Domain Released (day 79+)

  • After pending delete completes, the domain may become publicly available again
After the Guaranteed Renewal Window (expirationGracePeriod) ends, treat the domain as gone from your API account. Any later renew or redeem action is best-effort through the name.com web UI only. Do not assume Get/List or Renew Domain will succeed.

​
Where to take each action

​
Webhooks for lifecycle changes

Subscribe via Subscribe to Notification. See Webhooks overview and HMAC examples.

​
Important notes

  • Timelines and behavior vary by TLD and registry. Confirm the Guaranteed Renewal Window with expirationGracePeriod via Get TLD Requirements.
  • Some TLDs have a shorter Guaranteed Renewal Window than 25 days.
  • Redemption fees and policies are registry-specific.
  • To minimize risk, encourage users to enable auto-renew and send clear customer reminders before expiration.
  • Post-expiration holds for some reseller configurations are covered under ExpirationClientHold.