Subscriptions
How Subscriptions Work
autoRenew is enabled, or manually by calling POST /subscriptions/renew-subscriptions.EXPIRED and the mailbox is disabled.Subscription Statuses
| Status | Mailbox works? | Description |
|---|---|---|
ACTIVE | ✅ Yes | Subscription is current |
RENEWING | ✅ Yes | Renewal payment is processing |
PAST_DUE | ⚠️ Limited | Payment failed |
CANCELLED | ❌ No | Explicitly cancelled by partner |
EXPIRED | ❌ No | Subscription not renewed — mailbox disabled |
State Machine
[ACTIVE] ──→ [RENEWING] ──→ [ACTIVE] (payment succeeded)
↓
[PAST_DUE] (payment failed)
├──→ [ACTIVE] (renewed via API or auto-renew)
└──→ [EXPIRED] (not renewed)
[ACTIVE] ──→ [CANCELLED] (partner cancelled)Billing Cycles
| Cycle | Price | Notes |
|---|---|---|
MONTHLY | $3.00/mailbox/month | Billed monthly |
INFO
POST /subscriptions/recreate to reset pricing without mailbox downtime. See 1+ Year Subscriptions.Available Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /subscriptions?userId= | List subscriptions for a user |
POST | /subscriptions/renew-subscriptions | Manually renew one or more subscriptions |
POST | /subscriptions/toggle-autorenewal | Enable or disable auto-renewal per subscription |
POST | /subscriptions/cancel | Cancel one or more subscriptions immediately |
POST | /subscriptions/recreate | Recreate subscriptions to reset pricing |
Webhook Events
| Event | Fired when |
|---|---|
subscription.renewing | Renewal payment is being processed |
subscription.renewal.success | Renewal payment succeeded |
subscription.renewal.failed | Renewal payment failed → PAST_DUE |
subscription.past_due | Subscription entered past-due state |
subscription.cancelled | Cancelled by partner |
subscription.expired | Subscription not renewed → EXPIRED |
subscription.updated | Subscription record updated |
Scenarios
Recover from PAST_DUE
Receive webhook
subscription.past_due fires — identify the affected subscriptions.Update payment method
Customer updates their payment method via your UI and billing provider.
Renew
Call
POST /subscriptions/renew-subscriptions with the affected subscriptionIds, or enable auto-renew via POST /subscriptions/toggle-autorenewal.Confirm recovery
Listen for
subscription.renewal.success — mailbox is restored.Cancel a Subscription
DANGER
POST /subscriptions/cancel is immediate and permanent. The mailbox moves to EXPIRED instantly with no prorated refunds.WARNING
autoRenew is on, the subscription moves to RENEWING on its renewal day. Calling POST /subscriptions/cancel during that window is rejected with 400 "Subscription is under renewal, cannot be cancelled.". Wait for renewal to finish (listen for subscription.renewal.success), or disable autoRenew before the renewal date with POST /subscriptions/toggle-autorenewal, then cancel.Subscription Auto Renewal
POST /subscriptions/toggle-autorenewal instead.Reset Long-Running Subscription Pricing
Identify affected subscriptions
GET /subscriptions?userId= — find subscriptions approaching or past 12 months.Recreate subscriptions
POST /subscriptions/recreate with subscriptionIds or domainNames. Pricing resets to $3/month with no mailbox downtime.Avoid These Common Issues
POST /subscriptions/renew-subscriptions or ensure auto-renew is enabled. Subscriptions that are not renewed will expire.CANCELLED is a permanent partner action. EXPIRED means the subscription was not renewed — it can still be recovered. Treat these differently in your UI.POST /subscriptions/cancel expires the mailbox instantly. Use toggle-autorenewal if you only want to stop future renewals.autoRenew on, the subscription is RENEWING on its renewal day, and POST /subscriptions/cancel is rejected with 400 "Subscription is under renewal, cannot be cancelled.". Disable auto-renew before the renewal date, or wait until renewal completes, then cancel.POST /subscriptions/recreate proactively to reset the cycle without downtime.Next Steps
Modified at 2026-11-06 05:35:04