Domain Events

Domain events are triggered when orders are placed to register domains or when domain registrations are renewed.

Overview

The domain event lifecycle occurs in three scenarios:

New domain registration — When a user orders a new domain

Domain renewal — When an existing domain's registration period approaches expiration

Expiry — When a domain lapses at the registrar: first domain.grace_period (still renewable), then domain.expired (gone)

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

Payment processing fails

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

domain.grace_period

The domain has reached its registrar expiry date and entered a 7-day renewal grace window. The registration is still recoverable at this point — this is the event you act on.

The domain.grace_period webhook is sent when the domain has already expired at the registrar, but the domain is still within its 7-day grace window during which it can be renewed.

Mailbox subscription renewals on this domain are blocked while it stays in grace.

Example Payload

{
  "event": "domain.grace_period",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
    "domainName": "company.com",
    "expireOn": "2026-03-08T23:59:59.000Z"
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"domain.grace_period"`
`eventId`	string	Unique identifier for this event
`data.userId`	string	ID of the user who owns the domain
`data.domainId`	string	Unique domain identifier
`data.domainName`	string	The domain that entered grace (e.g., `company.com`)
`data.expireOn`	ISO 8601	Registrar expiry timestamp. The grace window closes 7 days after this, end of day UTC

What to do

Renew immediately — call POST /domains/renew with domainNames: ["company.com"]. This is the only window in which renewal is possible

Notify the customer — tell them mailboxes on this domain stop working if the domain lapses, and that their subscription cannot renew until the domain is renewed

domain.expired

The domain is gone at the registrar. The 7-day grace window closed without a renewal, and the registration is no longer recoverable through the API.

Treat it as terminal, not actionable — this is a reconciliation signal. Mark the domain dead on your side, deactivate or archive the mailboxes attached to it, and stop any sending campaigns pointed at it. Do not queue a renewal — it will be rejected

Example Payload

{
  "event": "domain.expired",
  "eventId": "6SSHBXWR3N4JEKGRQSG3KW3D76N6",
  "data": {
    "userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
    "domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
    "domainName": "company.com",
    "expireOn": "2026-03-08T23:59:59.000Z"
  }
}

Payload Schema

Field	Type	Description
`event`	string	Always `"domain.expired"`
`eventId`	string	Unique identifier for this event
`data.userId`	string	ID of the user who owned the domain
`data.domainId`	string	Unique domain identifier. Still resolvable via `GET /domains/domain`, which now returns status `EXPIRED`
`data.domainName`	string	The expired domain name
`data.expireOn`	ISO 8601	The original registrar expiry timestamp — not the date this event fired. Grace ended 7 days after this

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 reaches expireOn, it enters a 7-day grace period where it can still be renewed — you receive domain.grace_period. Once that window closes the domain is gone at the registrar and you receive domain.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.

Overview#

domain.order.success#

When it occurs#

Example Payload#

Payload Schema#

domain.order.failed#

When it occurs#

Example Payload#

Payload Schema#

Common failure reasons#

Notes#

domain.renewal.success#

When it occurs#

Example Payload#

Payload Schema#

domain.renewal.failed#

When it occurs#

Example Payload#

Payload Schema#

domain.grace_period#

Example Payload#

Payload Schema#

What to do#

domain.expired#

Example Payload#

Payload Schema#

Notes#

Next Steps#

Overview

domain.order.success

When it occurs

Example Payload

Payload Schema

domain.order.failed

When it occurs

Example Payload

Payload Schema

Common failure reasons

Notes

domain.renewal.success

When it occurs

Example Payload

Payload Schema

domain.renewal.failed

When it occurs

Example Payload

Payload Schema

domain.grace_period

Example Payload

Payload Schema

What to do

domain.expired

Example Payload

Payload Schema

Notes

Next Steps