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 Status & Renewal Eligibility Matrix#
| Status | Eligible for Renewal? | Auto-Renew Behavior | Action Required |
|---|
ACTIVE (expires >45 days) | ❌ No | Waits until within 45 days | None |
ACTIVE (expires ≤45 days) | ✅ Yes | Eligible; will auto-renew on schedule if enabled | Call renew endpoint or enable auto-renew |
GRACE_PERIOD (≤7 days after expiration) | ✅ Yes | Eligible; may still auto-renew if enabled | Call renew endpoint or enable auto-renew |
EXPIRED (>7 days post-expiration) | ❌ No | Auto-disabled; recovery requires registrar escalation | Contact registrar support |
RENEWING (temporary state) | — | Request in progress | Wait for webhook confirmation |
Domain Renewal Workflow#
Step 1: Retrieve Renewal Pricing#
Call POST /domains/renewal-price with these parameters:domains (optional array of domain names)
data field and renewal period will be default for 1 year
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 12:47:44
