Engineering
What happens when you can't pay for a renewal as a reseller
Numbers, mailboxes and domains each fail a renewal differently: one event and no grace period, three days before deletion, or daily retries until the domain expires.
The short answer
A phone number rental gets one automatic renewal attempt; if the wallet is short it sends a single number.rental.renewal_failed event and the number simply expires on time. Mailboxes renew together per domain each month; if the wallet is short you get a mailbox_domain.renewal_failed event with a deletesAt date, the charge is tried again, and a domain still unpaid three days later is deleted with all its mailboxes. A domain with auto-renew on is renewed 30 days before it expires; if the wallet is short, domain.renewal_failed is raised and the renewal is tried again daily until the domain expires. These three behaviours are different today, not three settings of the same feature.
A reseller's customer is relying on a renewal happening without being asked, so a renewal failure is a bigger problem for the reseller than it ever is for the end buyer: the buyer just notices the product stopped working, while the reseller is the one who has to know why, by when, and what to say. On ResellerHQ today, the answer depends entirely on which product failed. A phone number rental tries to renew once and, if the wallet is short, sends one event and lets the number expire on schedule. Mailboxes get three days, with the charge tried again, before their domain is deleted with all of them. A domain with auto-renew on starts trying 30 days before it expires and tries again daily until it does.
Those are three different, documented behaviours, not three settings of one "auto-renew" feature. This article compares them side by side, each claim pointing at the guide that documents it, and says what a reseller should be telling their own customer in each case.
Why does a failed renewal matter more to a reseller than to the buyer?
The end buyer who rents a number through a reseller's product, or runs their mail on a mailbox a reseller sold them, has no idea a wallet exists. They expect the thing they're paying for to keep working, silently, the way it did last month. When a renewal fails on the reseller's side, the buyer's experience is not "my payment failed" - it is "the product broke for no reason I was told about." A silent lapse is worse for the reseller's reputation than a loud one, because the buyer has no way to tell the difference between a bug and an unpaid wholesale bill.
That is why the shape of the grace period matters as much as its length. A warning a reseller can forward to their own customer is useful. A lapse that happens with no window to react to is not something a reseller can get ahead of at all - they can only find out after the fact and apologise.
What happens when a phone number rental can't renew?
Setting autoRenew on a number rental, with PATCH /v1/numbers/{id}, has it extended "shortly before it ends." If the wallet cannot cover that charge when the attempt is made, you get a single number.rental.renewal_failed event, and the number expires on time - the rental simply ends when its paid-for period runs out (numbers guide, "Renew" section). There is one attempt and one event; the docs describe no retry and no additional grace window after that.
Practically, this means the warning and the loss arrive together. By the time your system has seen number.rental.renewal_failed, the number's clock has already run out or is about to - "shortly before it ends" is the only lead time you get, and it is the platform renewing on your behalf, not a notice sent to you in advance of that attempt. If your customer is relying on that number to keep receiving SMS, the only way to avoid a surprise lapse is to watch the wallet balance against upcoming autoRenew charges yourself, before the attempt happens, not after.
What happens when mailboxes can't renew?
Mailboxes renew per domain, not one by one. Every active mailbox on a domain renews together, monthly, on the date the domain's first mailbox was ordered, tracked as periodEndsAt. A successful charge sends mailbox_domain.renewed (mailboxes guide, "Renewal and deleting" section).
If the wallet can't pay, the mailboxes are not turned off straight away. Instead:
- You get one
mailbox_domain.renewal_failedevent for that month, carrying adeletesAtdate. - The charge is tried again, so topping up the wallet clears it without you doing anything else.
- A domain still unpaid three days later is deleted with all its mailboxes, and you get
mailbox_domain.deleted.
The warning always comes before the deletion, and three days is real reaction time, but it is short. Nothing already paid is refunded when a domain is deleted, and a deleted mailbox does not come back, so this is the renewal to watch most closely.
What happens when a domain can't renew?
Domains renew from the wallet when autoRenew is on, set with PATCH /v1/domains/{id}. New registrations start from the account's default. 30 days before such a domain would expire, it is renewed for a year at its own price, through the same path as a manual renewal (domains guide, "Auto-renew" section).
If the wallet cannot cover it, nothing is charged, domain.renewal_failed is raised with the reason, and the renewal is tried again daily until the domain expires. Separately, every domain, auto-renewing or not, sends domain.expiring at 60, 30, 7 and 1 days before it expires, with whether the wallet is already short of what a renewal would cost. A domain without autoRenew is only extended by sending POST /v1/domains/{id}/renew with the number of years to add, charged at the price the domain was registered at.
It's worth separating this from how domain renewal windows work at the registry level generally, since the terms get confused. ICANN describes an Auto-Renew Grace Period as a 45-day period following a domain name's expiration, during which a registrar can still choose to renew it, followed by a 30-day Redemption Grace Period and a 5-day Pending Delete stage before the name is released for anyone to register (ICANN: Auto-Renew Grace Period; ICANN FAQs for registrants). That window is a registry-and-registrar arrangement, and it exists whether or not any particular platform offers an "auto-renew" feature on top of it. ResellerHQ's own retries stop when the domain expires; what the registry allows after that is a separate question.
All three, side by side
| Phone number rental | Mailboxes | Domain | |
|---|---|---|---|
| Automatic renewal exists? | Yes, if autoRenew is set | Yes, always, monthly per domain | Yes, if autoRenew is set |
| Attempts if the wallet is short | One | Tried again until deletion | Daily until the domain expires |
| Grace period after a failed attempt | None | Three days | From 30 days before expiry until expiry |
| Warning event | number.rental.renewal_failed | mailbox_domain.renewal_failed | domain.expiring, then domain.renewal_failed |
| What happens if nothing is paid | Number expires on time | Domain and all its mailboxes deleted after three days, mailbox_domain.deleted | The domain expires |
| Time a reseller has to react | Essentially none - the event and the expiry coincide | Three days from the warning event | Up to 30 days from the first failed attempt |
Sources: numbers guide, mailboxes guide, domains guide.
What to tell your own customer, and when
The right message depends on which product is renewing, because the time you have to send it is different in each case. All of it assumes you are actually receiving the events - a renewal warning you never got is the same as no warning at all, so the webhook endpoint carrying these events needs the same retry and replay handling as any other (idempotency keys and webhooks for reseller APIs).
- Mailboxes. Tell your customer as soon as your system sees
mailbox_domain.renewal_failed. You have three days before the domain and its mailboxes are deleted, so this is a warning you can act on, but only if you act quickly - top up the wallet, or let them know their mailboxes are at risk and why. - Phone number. By the time
number.rental.renewal_failedarrives, the number is expiring on schedule regardless. The useful message has to go out before the renewal attempt, not after - watch your own wallet balance against numbers withautoRenewset and top up ahead of the renewal date, since the event itself is notice of a done deal, not a chance to fix it. - Domain.
domain.expiringarrives 60, 30, 7 and 1 days before expiry, anddomain.renewal_failedfrom 30 days out if the wallet is short. Either is early enough to pass on to your customer and still fix the balance in time.
How this differs from the general wallet mechanics
This article is about renewal-specific timing and notification - what gets retried, for how long, and which event fires when. It is not about how the wallet itself holds, captures and releases money for a single order, or what happens when an upstream provider's answer is unclear. That ledger-level mechanics - holds, double-entry journal lines, and the case where a hold never settles because a provider never answers - is covered in prepaid wallet billing for resellers. Read that one for the money model underneath every charge mentioned here; read this one for what happens when a specific renewal charge, placed against that wallet, doesn't clear.
The limits today
Phone numbers and mailboxes can be ordered on live accounts. Domains run in the sandbox only for now: their live routes answer 422 not_available until this deployment is given a registrar key (domains guide). None of the renewal behaviour above changes between sandbox and live - it is the same code path. The sandbox is open to test any of these three renewal paths with test funds at /signup.
Questions
- ResellerHQ tries the renewal once, shortly before the rental's current period ends. If the wallet cannot cover it, you receive a single number.rental.renewal_failed event and the number expires on time. There is no retry and no grace period after that event.
- Every active mailbox on a domain renews together, monthly. If the wallet cannot pay, you receive one mailbox_domain.renewal_failed event for that month with a deletesAt date, and the charge is tried again, so topping up the wallet clears it. If it is still unpaid three days later, the domain is deleted with all its mailboxes and you receive mailbox_domain.deleted.
- Yes, when autoRenew is on for the domain. 30 days before it would expire, the domain is renewed for a year from the wallet. If the wallet cannot cover it, nothing is charged, domain.renewal_failed is raised, and the renewal is tried again daily until the domain expires. Domains can be ordered in the sandbox today; on the live side the domain routes answer 422 not_available until this deployment is given a registrar key.
- For mailboxes, three days from the first failed charge, and the mailbox_domain.renewal_failed event always comes first. For a phone number, none: the single renewal_failed event and the number's expiry happen together. For a domain with auto-renew on, the most: the first attempt is 30 days before expiry and it is retried daily, and every domain also sends domain.expiring at 60, 30, 7 and 1 days before it expires.
- For mailboxes, tell them the same day you see mailbox_domain.renewal_failed; you have three days before the domain and its mailboxes are deleted. For a number, by the time you see the event the number is already gone, so the useful message is sent before the renewal date, not after. For a domain, domain.expiring and domain.renewal_failed give you weeks of notice to pass on.
- No. The wallet article covers how a single order reserves, captures and releases funds, and what happens when a provider's answer is unclear. This article covers what happens next, at renewal time, for a rental, a set of mailboxes or a domain that is already active - a separate set of behaviours documented product by product.