How to handle Stripe failed payments between subscription renewal vs upgrade?

Upgrade Workflow

A customer has one subscription (single or team), and the ability to add additional team members (which updates the subscription’s quantity).

If a customer currently has a single plan they can upgrade to a team plan. If anyone on a team plan needs additional seats, they simply change the quantity of their subscription.

I have webhooks currently set up for: customer.subscription.updated, customer.subscription.deleted, invoice.paid, and invoice.payment_failed.


  • If a payment fails during a subscription’s renewal, I would like the subscription to be canceled after the retry limit is hit.
  • If a payment fails during a subscription upgrade, I would like the previous subscription to remain with no cancellation.


Currently, in the dashboard, I have Subscription Status (found in Manage Failed Payments) set to cancel subscription if all retries failed.

Will this cancel the subscription in the case of all invoices, that have reached the retry limit, such as for renewals (invoice object’s billing_reason: "subscription_cycle") and upgrades (billing_reason: "subscription_update")?

If yes I’ll need to turn this off, but what is the standard way to handle such a scenario through my webhooks?


Thank you for visiting the Q&A section on Magenaut. Please note that all the answers may not help you solve the issue immediately. So please treat them as advisements. If you found the post helpful (or not), leave a comment & I’ll get back to you as soon as possible.

Method 1

I think you’ve got this pretty close to solved from you question. The invoice.payment_failed event is what you are looking for. So here’s how I would approach this:

Dashboard Settings


  • Deactivate the setting to cancel the subscription if the invoice payment fails
  • Or keep it but set to the max number of days (15) as a fail safe in case your other logic fails to catch a situation where you should cancel the subscription

Webhook Handling

If the event type is invoice.payment_failed, inspect invoice.billing_reason to determine whether it was in response to a renewal or an update. For either process, you can access the subscription ID in invoice.subscription.

if invoice.billing_reason == "subscription_cycle":
    # Renewal Payment Failure - Cancel the subscription for this customer
    # Take other measures (like emailing the customer)

elif invoice.billing_reason == "subscription_update":
    # Upgrade Payment Failure - downgrade subscription

Apologies for the Python, it’s the language I’m most comfortable in 🙂

All methods was sourced from or, is licensed under cc by-sa 2.5, cc by-sa 3.0 and cc by-sa 4.0

0 0 votes
Article Rating
Notify of

Inline Feedbacks
View all comments
Would love your thoughts, please comment.x