This article outlines the domain renewal options, post-expiration lifecycle, required customer communications, and webhooks for managing domain inventory via the Core API.
Renewal Options
You can renew domains before they leave your account inventory using two methods:
-
Auto-Renew
Timing: Configurable to ~30 days or ~7 days before expiration.
Setup: Enable per domain via the
autorenewEnabledparameter on Update Domain or within the name.com portal. Account-wide settings are located under payment/account settings.
-
Manual Renewal
Execution: Renew programmatically using Renew Domain or manually through the name.com portal.
Best Practice: Batch renewals (up to ~500 at a time) and always include idempotency keys.
Billing Control: Domain renewals are non-refundable. You can charge customers prior to renewing to prevent dispute issues.
Post-Expiration Lifecycle
If a domain is not renewed prior to its expireDate, it progresses through the following stages:
| Stage | Timeline (Typical gTLDs) | Core API Availability | Key Actions & Notes |
| 1. Expiration | Day 0 | In Account | DNS, web, and email services may halt depending on registry locks. |
| 2. Guaranteed Renewal Window | Days 1–25 | In Account |
Standard renewal pricing applies via API or UI. Check specific TLD lengths using expirationGracePeriod on Get TLD Requirements.
|
| 3. Extended Renewal Window | Days 26–43 | Removed from API | Domain leaves API inventory. Best-effort renewal is available strictly via the name.com Renewal Center. |
| 4. Redemption Grace Period | Days 44–74 | Removed from API | Recovery requires a registry-specific redemption fee plus renewal term via the Renewal Center. |
| 5. Pending Delete | Days 75–79 | N/A | Scheduled for final deletion; recovery is impossible. |
| 6. Released | Day 79+ | N/A | Domain becomes publicly available for new registration. |
Note: Treat domains as removed from your API account once the Guaranteed Renewal Window (
expirationGracePeriod) ends. Subsequent recovery is best-effort via the web UI only.
Registrant Communications & Compliance
ICANN Requirements: If managing registrant communications, you must send pre-expiry reminders and a post-expiry recovery notice.
Recommended Flow: Send informational reminders at ~30 days and ~7 days prior to expiry, followed by order confirmations once renewal completes.
Review Registrant Communications for exact timing and content models.
Webhook Notifications
Subscribe to webhooks via Subscribe to Notification to track lifecycle events:
domain.expiration: Fires at Day 0 when the domain enters the Guaranteed Renewal Window. Do not remove the domain from your database yet.account.domain.removal(reason: expiration): Fires when the Guaranteed Renewal Window ends and the domain leaves your API inventory. Archive or drop the domain from your database.account.domain.removal(reason: agp_refund/administrative): Fires when a domain is removed due to AGP refund or administrative/ops action.domain.lock.status_change: Fires when domain locks change, such asExpirationClientHold
Important notes
Variable Rules: Renewal windows, redemption fees, and policies vary by TLD and registry. Check specific requirements via Get TLD Requirements (some renewal windows are shorter than 25 days).
Prevention: Minimize domain loss by recommending auto-renew and sending timely expiration reminders.
Reseller Holds: Post-expiration hold behaviors for specific configurations are managed under ExpirationClientHold.
0 Comments