Detect automatic cancellation of Stripe subscription with cancel_at_period_end true

Question

In my Stripe-Connect app I want to handle the Stripe customer.subscription.deleted webhook generated when a subscription is automatically cancelled after failed payment attempts (based on the subscription settings for failed payments).

The Stripe documentation states: "You can see that a subscription was canceled automatically–as opposed to by your request–if the customer.subscription.deleted event’s request property is null." See also Detect if subscription is cancelled automatically.

However, it seems that if a subscription has cancel_at_period_end set to "true", the customer.subscription.deleted event’s request property is null even if the subscription ends "naturally" at the end of the period, and not as a result of failed payment attempts.

So, my question is, how can I detect that a subscription with cancel_at_period_end set to true has been cancelled because of failed payment attempts?

Answer 1

There's no way to distinguish between those two cases at the moment unfortunately. What I'd recommend is to store on your end that you have marked the subscription to cancel at the end of the current period. That way when you get the customer.subscription.deleted event, you can check whether it came from a failed payment or not based on that flag on your end.

Another solution would be to look at the latest invoice for that subscription. You would be able to look at the attempt_count property to see how many retries were made on it and infer whether the cancelation came from the last attempt or not.

Answer 2

The subscription object now has a field cancellation_details.reason which can differentiate cancellation_requested and payment_failed:

Screenshot retrieved from https://stripe.com/docs/api/subscriptions/object#subscription_object-cancellation_details-reason on 9/12/2023