Engineering
What happens when you can't pay for a renewal as a reseller
Numbers, mailbox licences and domains each fail a renewal differently: one event and no grace period, a week of retries, or no automatic renewal at all.
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. A mailbox licence instead gets a week-long grace period, with the charge retried every minute and a licence.renewal_failed warning before any cancellation. A domain has no automatic renewal built into the API at all, so nothing happens on its own either way - someone has to call renew before it lapses. 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. A mailbox licence gets a week-long grace period with the charge retried every minute. A domain gets neither, because automatic renewal for domains is not built at all - someone has to call renew themselves.
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 licence 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 a mailbox licence can't renew?
A mailbox licence is charged price × seats automatically when its current paid period, tracked as periodEndsAt, ends. A successful charge fires licence.renewed and moves periodEndsAt on by a month (mailbox licences guide, "Monthly renewal" section).
If the wallet can't pay, the licence is not turned off. Instead:
- You get one
licence.renewal_failedevent for that month, carrying acancelsAtdate. - The licence now carries
unpaidSinceandcancelsAt- bothnullagain once nothing is owed. - The charge is retried every minute, so topping up the wallet at any point clears it without you doing anything else.
- A licence still unpaid a week after that first failed attempt is cancelled, with a
licence.cancelledevent whosereasonis"unpaid".
The docs are explicit that "a licence is never cancelled without" the warning coming first: licence.renewal_failed always fires before licence.cancelled can. That week is real reaction time, not a formality - a reseller who sees the warning event has a full seven days to fund the wallet before the licence disappears.
One more detail worth knowing: a licence left unbilled for a month or more is only charged for one month when it is finally billed, not for every month that was missed (mailbox licences guide, "Monthly renewal" section).
What happens when a domain can't renew?
Nothing - because there is nothing to fail. Automatic renewal is not part of the domains API: the "Not built yet" section of the domains guide states plainly that "automatic renewal" is not built, alongside DNS record management and transfers (domains guide). A domain is only extended by sending POST /v1/domains/{id}/renew with the number of years to add - one to ten, defaulting to one - charged "at the price the domain was registered at" (domains guide, "Renew" section).
There is no autoRenew flag to set on a domain, no retry, and no renewal-failure event, because none of those things exist for this product today. If nobody calls renew before a registration's current years run out, the ResellerHQ API does not watch for that, warn about it or react to it in any documented way. This is the one case in the comparison where "what happens at the grace period" is the wrong question, because there is no automated process to have a grace period around.
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. It is not something the ResellerHQ API builds, exposes, or passes through today - ResellerHQ's domains run in the sandbox only, and sandbox domains are not registered anywhere (domains guide). The practical point for a reseller is the same either way: don't assume any safety net is watching a domain's expiry date for you. Track it yourself and call renew.
All three, side by side
| Phone number rental | Mailbox licence | Domain | |
|---|---|---|---|
| Automatic renewal exists? | Yes, if autoRenew is set | Yes, always, when periodEndsAt passes | No - not built |
| Attempts if the wallet is short | One | Retried every minute | N/A - nothing is attempted automatically |
| Grace period after a failed attempt | None | One week | N/A |
| Warning event | number.rental.renewal_failed | licence.renewal_failed | None |
| What happens if nothing is paid | Number expires on time | Licence cancelled after a week, licence.cancelled with reason: "unpaid" | Nothing automated; the registration simply runs past its paid years unless you call renew |
| Time a reseller has to react | Essentially none - the event and the expiry coincide | A full week from the warning event | However long you choose to track it yourself |
Sources: numbers guide, mailbox licences 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).
- Mailbox licence. Tell your customer as soon as your system sees
licence.renewal_failed. You and they both have a week before anything is cancelled, so this is a warning you can actually act on - top up the wallet, or let them know their seats 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. There is no event to wait for. Whatever schedule you tell your customer about has to come from tracking the registration's renewal date in your own systems and calling
renewyourself, well before it matters.
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 are the only one of the three products with a live path; mailbox licences and domains run in the sandbox only, where their live routes answer 422 not_available and nothing is provisioned with a real registrar, Google or Microsoft (domains guide, mailbox licences guide). None of the renewal behaviour above changes between sandbox and live - it is the same code path - but it is worth knowing which products you can actually put a paying customer's domain or seats on today. 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.
- The licence is not switched off. You receive one licence.renewal_failed event with a cancelsAt date, and the licence carries unpaidSince and cancelsAt until the balance is settled. The charge is retried every minute, so topping up the wallet at any point in that week clears it. If it is still unpaid a week after the first failed attempt, the licence is cancelled with a licence.cancelled event whose reason is unpaid.
- No. Automatic renewal is not part of the domains API today. A domain is only renewed when you send a POST request to its renew endpoint, adding one to ten years at a time. Nothing watches the registration's end date on your behalf.
- For a mailbox licence, a full week from the first failed charge, and the licence.renewal_failed event always fires before any cancellation. For a phone number, none: the single renewal_failed event and the number's expiry happen together. For a domain, the question does not apply in the same way, because nothing automatic is watching the renewal date at all; whatever warning exists has to come from your own systems.
- For a licence, you can tell them the same day you see licence.renewal_failed and still have a week before cancellation. 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, there is no event to react to at all, so your customer needs to hear from you on whatever schedule you build yourself.
- 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 licence or a domain that is already active - a separate set of behaviours documented product by product.