Domain events are triggered when orders are placed to register domains or when domain registrations are renewed.
Overview#
The domain event lifecycle occurs in two scenarios:1.
New domain registration — When a user orders a new domain
2.
Domain renewal — When an existing domain's registration period approaches expiration
domain.order.success#
This event is triggered when a domain is successfully registered with the registrar and added to the user's account.When it occurs#
User places a domain order through the platform
The domain registrar confirms successful registration
The domain becomes active and accessible
Example Payload#
{
"event": "domain.order.success",
"eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "johndoe@company.com",
"orderId": "NQ682GAVFTMYC2H6C87PPKPG5WXV",
"domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
"domainName": "company.com",
"creationtime": "2024-03-08T23:59:59Z",
"expiryDate": "2025-03-08T23:59:59Z",
"price": 15.88
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "domain.order.success" |
eventId | string | Unique identifier for this event |
data.userId | string | ID of the user who placed the order |
data.userEmail | string | User's email address |
data.orderId | string | Unique order identifier |
data.domainId | string | Unique domain identifier |
data.domainName | string | The registered domain name (e.g., company.com) |
data.creationTime | ISO 8601 | Timestamp when domain was registered |
data.expiryDate | ISO 8601 | Timestamp when domain registration expires |
data.price | number | Price paid for the domain |
domain.order.failed#
This event is triggered when a domain order fails to be registered. This could happen due to domain availability, restrictions, or registrar errors.When it occurs#
User orders a domain that's already taken
Domain name contains restricted phrases
Registrar has connectivity issues
User has insufficient wallet balance
Example Payload#
{
"event": "domain.order.failed",
"eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "jean@gmail.com",
"message": "Domain contains restricted phrase(s)",
"domainName": "norton360.com",
"orderId": "WR3N4JEW3D76N6KGRQSG36SSHBXK",
"price": 15.88
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "domain.order.failed" |
eventId | string | Unique identifier for this event |
data.userId | string | ID of the user who placed the order |
data.userEmail | string | User's email address |
data.orderId | string | Unique order identifier |
data.domainName | string | The domain name that failed to register |
data.message | string | Human-readable reason for failure |
data.price | number | Price that was attempted to charge |
Common failure reasons#
"Domain unavailable" — Already registered by someone else
"Domain contains restricted phrase(s)" — Domain name violates policies
"Registrar error" — Technical issue with registrar
"Insufficient wallet balance" — User needs to add funds
"Invalid domain format" — Domain name doesn't meet requirements
Notes#
Multiple domains per order: An order can include multiple domains. You'll receive separate domain.order.* events for each domain.
domain.renewal.success#
This event is triggered when an existing domain registration is successfully renewed for another term.When it occurs#
A domain's registration period is approaching expiration
Renewal is processed (automatically or manually)
Registrar confirms the renewal
Domain registration is extended by 1 year
Example Payload#
{
"event": "domain.renewal.success",
"eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "johndoe@company.com",
"domainName": "company.com",
"domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
"years": 1,
"price": 26.90,
"expireOn": "2026-03-08T23:59:59.000Z"
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "domain.renewal.success" |
eventId | string | Unique identifier for this event |
data.userId | string | ID of the user |
data.userEmail | string | User's email address |
data.domainName | string | The renewed domain name |
data.domainId | string | Unique domain identifier |
data.years | number | Number of years renewed for (usually 1) |
data.price | number | Price of domain renewal |
data.expireOn | ISO 8601 | New expiration timestamp |
domain.renewal.failed#
This event is triggered when a domain renewal fails. This is separate from subscription renewal and indicates the domain registration itself couldn't be renewed.When it occurs#
Renewal was charged but the registrar rejected it
Domain has been deleted at the registrar
Registrar had an error processing the renewal
Domain has too many rule violations
Important: Subscriptions linked to this domain cannot be renewed until the domain is fixed
Example Payload#
{
"event": "domain.renewal.failed",
"eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "johndoe@company.com",
"domainName": "company.com",
"domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
"years": 1,
"error": "Registrar renewal failed with an unknown error."
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "domain.renewal.failed" |
eventId | string | Unique identifier for this event |
data.userId | string | ID of the user |
data.userEmail | string | User's email address |
data.domainName | string | The domain that failed to renew |
data.domainId | string | Unique domain identifier |
data.years | number | Years that renewal was attempted for |
data.error | string | Technical error message from registrar |
Notes#
Domain renewal ≠ Subscription renewal: A domain is the actual registration with the registrar. A subscription is the mailbox accounts provisioned on that domain. Both can be renewed independently.
Grace period: After a domain expires, it enters a grace period (usually 7 days) where it can still be renewed. After that, it's expired.
Next Steps#
Domains
Manage domains, forwarding, and status transitions.
Mailbox Events
What happens after domain registration succeeds.
Subscription Events
How mailbox subscription renewal works. Modified at 2026-08-05 16:12:50
