Subscription events are triggered when mailbox subscriptions are renewed or cancelled. A subscription is the ongoing service that keeps mailbox accounts active after they're created.
Overview#
Subscriptions are separate from domain registrations. Here's the relationship:Domain → Registered once, renewed periodically (yearly)
Subscription → Billing period for mailboxes (monthly, yearly, etc.), can be renewed or cancelled independently
subscription.renewal.success#
This event is triggered when a mailbox subscription is successfully renewed for the next billing period.When it occurs#
A subscription renewal period arrives (e.g., yearly renewal date)
The linked domain is active and not expired
Billing is processed successfully
Subscription is extended for another period
Example Payload#
{
"event": "subscription.renewal.success",
"eventId": "6SSHBXWQ3N3JEKHRQ763KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "johndoe@company.com",
"subscriptionId": "YC2H6C87PPKPG5WXVNQ682GAVFTM",
"workspaceType": "GOOGLE",
"quantity": 3
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "subscription.renewal.success" |
eventId | string | Unique identifier for this event |
data.userId | string | User who owns the subscription |
data.userEmail | string | User's email address |
data.subscriptionId | string | Subscription being renewed |
data.workspaceType | string | "GOOGLE" or "MICROSOFT" |
data.quantity | number | Number of mailboxes in this subscription |
subscription.renewal.failed#
This event is triggered when a subscription renewal fails. This is different from domain renewal failure — it specifically means the mailbox subscription couldn't be renewed.When it occurs#
Subscription renewal date arrives
Linked domain is in GRACE_PERIOD (expired but recoverable)
Linked domain is EXPIRED (past grace period, deleted at registrar)
Mailbox accounts can't be renewed without an active domain
No billing is attempted until domain is fixed
Example Payload#
{
"event": "subscription.renewal.failed",
"eventId": "6SSHBXWQ3N3JEKHRQ763KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "johndoe@company.com",
"subscriptionId": "YC2H6C87PPKPG5WXVNQ682GAVFTM",
"domainId": "AH2BD0WYWSMQC9NQHTMES3TFK4TX",
"domainName": "company.com",
"domainStatus": "GRACE_PERIOD",
"reason": "Domain is in GRACE_PERIOD; subscription renewal was not attempted. Please renew the domain at registrar."
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "subscription.renewal.failed" |
eventId | string | Unique identifier for this event |
data.userId | string | User who owns the subscription |
data.userEmail | string | User's email address |
data.subscriptionId | string | Subscription that failed to renew |
data.domainId | string | Domain linked to this subscription |
data.domainName | string | Domain name |
data.domainStatus | string | "GRACE_PERIOD" or "EXPIRED" |
data.reason | string | Human-readable explanation |
subscription.cancelled#
This event is triggered when a mailbox subscription is cancelled because the user disabled auto-renewal and the current billing period has ended.When it occurs#
Current billing period expires
Subscription is no longer active
Example Payload#
{
"event": "subscription.cancelled",
"eventId": "6SSHBXWQ3N3JEKHRQ763KW3D76N6",
"data": {
"userId": "PWM7Y25RYZ450YNM8K8FX9GK5AHX",
"userEmail": "johndoe@company.com",
"subscriptionId": "YC2H6C87PPKPG5WXVNQ682GAVFTM",
"workspaceType": "GOOGLE",
"quantity": 3
}
}
Payload Schema#
| Field | Type | Description |
|---|
event | string | Always "subscription.cancelled" |
eventId | string | Unique identifier for this event |
data.userId | string | User who owned the subscription |
data.userEmail | string | User's email address |
data.subscriptionId | string | Subscription that was cancelled |
data.workspaceType | string | "GOOGLE" or "MICROSOFT" |
data.quantity | number | Number of mailboxes that were active |
Understanding the Subscription Flow#
Successful renewal cycle#
Subscription active
↓
Renewal date arrives
↓
subscription.renewal.success
↓
Next billing period starts
↓
(Cycle repeats at next renewal date)
Failed renewal (domain issue)#
Subscription active
↓
Renewal date arrives
↓
Domain check: EXPIRED or GRACE_PERIOD
↓
subscription.renewal.failed
↓
Mailboxes stay active until period ends
↓
User must renew domain before next renewal
Cancellation flow#
Subscription active
↓
User disables auto-renewal
↓
Current period expires
↓
subscription.cancelled
↓
Mailboxes deactivated
Notes#
Subscription and domain are independent — You can have a domain without subscription.
Auto-renewal can be toggled — Users can enable/disable via dashboard
See also#
Modified at 2026-04-03 08:38:38
