What happens when a renewal fails
For a subscription that charges automatically, a failed renewal payment makes the subscription past_due. Stripe keeps generating invoices and tries again according to your retry settings. When the retries end, your failed-payment settings in the Stripe Dashboard decide what the subscription becomes: it stays past_due, moves to unpaid, or moves to canceled.
Each of those has a different effect on the license, and the choice is yours, so make it on purpose.
Smart Retries
Stripe describes Smart Retries as its automatic retry system for failed subscription and invoice payments. As of November 2026:
- It is on by default for new Stripe accounts, set to up to 8 retries within 2 weeks.
- You can pick a different window: 1 week, 2 weeks, 3 weeks, 1 month or 2 months.
- You can define a custom retry schedule instead.
- Stripe decides the timing of each retry. The documentation does not promise specific days, so do not write them in your terms.
Two webhook details matter if you build your own notifications. The invoice.payment_failed event carries an attempt_count, which tells you how many tries have failed. The next_payment_attempt field is no longer set in invoice.payment_failed events but in invoice.updated events.
What Stripe will not retry
| Situation | Retried? | What the customer must do |
|---|---|---|
| Insufficient funds, generic decline | Yes | Often nothing, the retry may succeed |
| No payment method on file | No | Add one |
| Hard decline: lost card, stolen card, pickup card, incorrect number | No | Replace the card |
| India-issued card | No | Stripe’s separate recurring-payment flow applies |
| Card needs authentication | Customer action needed | Complete the authentication |
Hard declines are the ones to watch, because Stripe stops quickly and the customer has no idea until the license ends. Send them an email on invoice.payment_failed with a link to your billing page.
What the license does at each step
Clavem keeps a license valid while the subscription status is active, trialing or past_due. It expires the license when the status is canceled, unpaid, incomplete_expired or paused, or when a customer.subscription.deleted event arrives. A paid renewal, signaled by invoice.paid, revives an expired license.
| Day | Stripe | License |
|---|---|---|
| 0 | Renewal fails. Subscription past_due |
Valid |
| 1 to 14 | Smart Retries run, up to 8 within 2 weeks by default | Valid |
| Any day in the window | A retry succeeds, or the customer pays | invoice.paid arrives, the expiry moves to the new period end plus three days |
| End of the window | Retries are exhausted. Stripe applies your failed-payment setting | Depends on the setting |
The three failed-payment settings, from Stripe’s documentation, have different results:
| Setting after retries | Subscription status | License |
|---|---|---|
| Cancel the subscription | canceled |
Expires when the status changes |
| Mark as unpaid | unpaid |
Expires when the status changes. Stripe stops attempting payment |
| Leave past due | past_due |
Stays valid. Invoices keep being generated and the customer may still be charged |
The third row is the trap. If your Stripe setting leaves the subscription past due, Clavem keeps treating it as entitled, because it deliberately keeps past_due valid while Stripe retries. The license then lasts until someone cancels the subscription. For software licensing, choose cancel or mark as unpaid, and check the setting in the Dashboard under billing settings.
The three-day margin
A subscription license’s expiry is the end of the paid period plus three days. That covers a renewal that settles late, for example when a bank takes a day to confirm. It is not the same as the retry window, which can be up to 2 weeks. For the interplay, see grace periods for expired licenses.
The app cannot see past due
A common surprise: the License API has no field for “payment failed”. The license says valid: true and status: active throughout the retry window. That is deliberate, since a failed payment is not a reason to lock out a paying customer, but it means your app cannot show a “please update your card” banner by itself.
Get the message to the customer another way:
- Stripe’s own customer emails for failed payments, expiring cards and payment methods that need an update, which Stripe’s documentation describes under revenue recovery.
- A link to the Stripe Customer Portal, where customers update their payment method. See Stripe Customer Portal for software.
- Your own email triggered by
invoice.payment_failed, which gives you control of the wording.
An expired license is different: the License API says so, with the text “This license key has expired.” Your app should show a renewal message for that state.
Test it before launch
You can reproduce every row without waiting two weeks. Create a customer on a Stripe test clock, attach the test card 4000 0000 0000 0341, which Stripe documents as attaching successfully and failing when charged, and subscribe. Then advance the clock through the renewal and the retry window, and look at the license in Clavem at each step. Repeat with 4242 4242 4242 4242 to confirm a successful renewal extends the expiry.
Check three things:
- The license stays valid while the subscription is
past_due. - The license expires when your configured end state arrives.
- Paying the open invoice revives the license.
Reduce failures before they happen
Cards expire, get replaced or hit limits, and most of those failures are fixable. Stripe’s revenue-recovery documentation lists customer email notifications for a payment that fails, a card that expires and a payment method that needs an update, so turn on the ones that fit your product, and put a payment-method link in every receipt. Offer an annual plan, since a customer who pays once a year fails once a year. The best retry system still loses some customers who simply forgot, so a short, friendly email at the point of failure recovers more than any schedule.
What to say in the app
The License API gives your app only a few states to work with, so the wording is simple. Match each state with a message and an action.
| What the app learns | Message | Action offered |
|---|---|---|
valid: true |
Nothing | Nothing |
valid: false, status expired |
“Your subscription has ended. Renew to keep using the paid features.” | A renewal link that opens your Stripe checkout or portal |
valid: false, status disabled |
“This license was refunded or revoked.” | A support contact |
Offline, token past refresh_by |
“Connect to the internet to check your license.” | Retry |
Keep the free features of the app working in the expired state, and never delete the customer’s own data. A customer who comes back after a card problem should find their work where they left it.
Doing this with Clavem
Clavem follows the Stripe events and needs nothing from you beyond the connected account. The only decision is Stripe’s end state after retries: choose cancel or unpaid. The Stripe documentation lists the subscription statuses and what each does to a license.
Questions
How many times does Stripe retry a failed subscription payment?
For new accounts, Stripe enables Smart Retries by default and configures it for up to 8 retries within 2 weeks. You can change the window to 1, 2 or 3 weeks, 1 month or 2 months, or define a custom schedule.
Which failed payments does Stripe not retry?
Stripe does not retry when no payment method is available, when the issuer returns a hard decline code such as a lost or stolen card or an incorrect number, or for India-issued cards. Those customers must act, for example by adding a new card.
Can my app tell that a payment failed?
Not through the License API. A past due subscription still validates as valid while Stripe retries, because the license is meant to stay usable. Tell customers through Stripe's emails, the Customer Portal and your own messages.
Sources
- Stripe Billing, revenue recovery and customer email notifications (as of November 2026)
- Stripe, automate payment retries with Smart Retries (as of November 2026)
- Stripe Billing, how subscriptions work and handling unpaid subscriptions (as of November 2026)
- Stripe testing documentation, decline-after-attaching test card (as of November 2026)