Domain renewal extends your domain registration and keeps it active. This guide covers the renewal process, eligibility requirements, and best practices.Important Note: Domain renewal operates independently from mailbox (subscription) renewal. These processes use separate endpoints, billing mechanisms and webhook systems.
Quick Reference#
| Aspect | Information |
|---|
| Default State | Auto-renew is disabled by default for all new domains |
| Renewal Window | APIs enforce a 45-day window preceding expiration |
| Grace Period | After a domain has expired, there is a 7-day grace period before it is fully expired. |
| Expired Domains | Handling varies by endpoint (refer to Eligibility Rules) |
| Payment Method | Partner wallet balance must be sufficient |
Domain Renewal Eligibility#
Domains can be renewed once they are within 45 days of their expiration date.Active domains that are nearing expiration (within 45 days)
Domains currently in the grace period (up to 7 days after expiration)
Note: You can disable auto-renew at any time, regardless of domain expiration status.
Domain Renewal Workflow#
Step 1: Retrieve Renewal Pricing#
Call POST /domains/renewal-price with these parameters:domains (optional array of domain names)
years (optional; defaults to 1 year)
data field.
Step 2: Execute the Renewal#
Select one of the following renewal methods:2.1 Manual Renewal (One-Time)#
Call POST /domains/renew with:Bulk Renewal: Omit the domains parameter (or send an empty array) to renew all eligible domains for the user. Ineligible domains will be reported as per-domain errors.
2.2 Automatic Renewal (Scheduled)#
Call PATCH /domains/toggle-auto-renew with:Bulk Auto-Renewal: Omit the domains parameter (or send an empty array) to enable auto-renewal for all user domains.
Note: Manual and automatic renewal are not mutually exclusive. Once auto-renewal is enabled, future renewals proceed automatically via scheduled processes (subject to eligibility, wallet balance, and pricing validation).
Step 3: Verify Renewal Status#
A 200 HTTP response indicates the request was accepted and queued—it does not guarantee immediate registrar completion.Confirm the final renewal state by:Calling GET /domains/by-user
Monitoring renewal webhooks
What Triggers Domain Renewal?#
1) API Request#
You explicitly call POST /domains/renew.2) Scheduled Auto-Renewal#
The renewal scheduler automatically processes domains when all conditions are met:Domain status is ACTIVE or GRACE_PERIOD
Renewal validation passes (eligibility window, wallet balance, pricing verification)
Renewal Events and Webhooks#
Subscribe to component webhooks via your partner dashboard for renewal event notifications.| Webhook Event | Description |
|---|
domain.renewal.success | Domain renewal completed and confirmed by registrar |
domain.renewal.failed | Domain renewal attempt failed |
subscription.renewal.failed | Mailbox subscription renewal skipped because domain is in GRACE_PERIOD or EXPIRED status |
What Happens If Renewal Doesn't Occur?#
Grace Period (Up to 7 Days Post-Expiration)#
API renewal may still be available
New mailbox provisioning requests is restricted
Subscription renewal attempts may fail with contextual webhook notifications
After Grace Period Ends#
Domain transitions to EXPIRED status
Auto-renewal is automatically disabled
Provider-specific service decommissioning processes may initiate
Avoid These Common Issues#
Confusing Processes: Domain renewal and mailbox subscription renewal are distinct operations with separate flows.
User ID Mismatches: Using an incorrect userId results in missing or empty results.
Transient Status: RENEWING status is temporary while an active renewal request is in progress.
Deferred Completion: A successful API response (200) does not guarantee immediate registrar completion.
TLD Variations: Registrar-level TLD rules may impose stricter requirements than internal grace period assumptions.
Bulk Operations: Always examine per-domain result entries in the response data array when performing bulk renewal calls, as some domains may succeed while others fail eligibility checks.
Modified at 2026-04-03 08:33:18
