Stripe customer subscription event behavior using webhook

Question

I have a monthly subscription product in Stripe.

If my user join to the monthly product, he pays the first month by credit card, then he uses his subscription normally during the time he is entitled to.

So that the user has the right to use the second month of subscription, Stripe will automatically charge the credit card for another month.

If the payment is successful, i know i will recieve a invoice.payment_succeeded event and this is enough to my.

But if the payment fails because some reason like: the user's credit card has expired:

1. I will recieve a customer.subscription.deleted or a customer.subscription.updated with status cancelled?

2. If i will recieve some of those events, they will be fired in the last day of the first month subscription? (because i need to know this status to cancel the user subscription in my api)

3. If instead of customer.subscription events, i wait for invoice.payment_failed event, this event will be fired in the last day of the first month subscription? (I don't want to be unfair to my user and remove their subscription privileges prematurely)

The Stripe documentation is not clear enough to ensure the clarity of this information

Answer 1

For every failed payment attempt on the recurring invoice payments, an invoice.payment_failed event will be sent. Only when the payment retries are exhausted, the subscription will be canceled, marked as unpaid or left it as past_due depending on your "Manage payments that require confirmation" setting in Dashboard.

Your system should listen to invoice.payment_failed event and follow the guide here to recover the payment failures: https://docs.stripe.com/billing/subscriptions/webhooks#payment-failures

Back to your questions:

I will recieve a customer.subscription.deleted or a customer.subscription.updated with status cancelled?

This depends on "Manage payments that require confirmation" setting. Subscriptions will only be canceled, i.e. sending customer.subscription.deleted event if you set to cancel a subscription if a recurring is incomplete.

---

If i will recieve some of those events, they will be fired in the last day of the first month subscription? (because i need to know this status to cancel the user subscription in my api)

If instead of customer.subscription events, i wait for invoice.payment_failed event, this event will be fired in the last day of the first month subscription? (I don't want to be unfair to my user and remove their subscription privileges prematurely)

If the subscription is set to being canceled, the event will be sent based on your period configuration in the Dashboard as well.

For example in the following screenshot, the subscription will be canceled with the event sent after 15 days of incomplete payment.