When an invoice fails all of its retried payments, the related subscription can be cancelled or marked as unpaid, depending on the subscription status action you choose in your settings. This behavior can be affected by longer retry schedules.
Long retry schedules that extend beyond a subscription’s billing period can cause the retry schedules of multiple invoices to overlap. In the rare case that one invoice fails all retries, but the latest invoice that is part of the same subscription is successfully paid, the subscription is left as-is and is not cancelled or marked as unpaid.
Take for example a subscription that has a billing period of one month, with a retry schedule of two months. Then suppose the following sequence of events occurs:
Jan 1: An invoice in_1 is issued and payment fails
Jan 2 - 30: Some retries are attempted and fail until there is only one retry left for in_1
Feb 1: An invoice in_2 is issued and payment is successful
Feb 10: The last retry for in_1 is attempted and fails
In the above case, the retry schedule for in_1 overlaps with the retry schedule for in_2, making it possible that the in_2 invoice receives successful payment before all retries for in_1 occur. Retries from in_1 are still liable to fail, and in this case, all of them do. When this happens, the subscription status is not changed because of the payment success misalignment. Explicitly, if the subscription status setting is set to “cancel the subscription,” then the subscription is not cancelled. If the setting is set to “mark the subscription as unpaid,” then the subscription is not marked as unpaid.
As stated above, it is specifically the latest invoice whose paid status matters. Take for example a subscription that has a billing period of one week, with a retry schedule of one month. The following sequence of events occurs:
Jan 1: An invoice in_1 is issued and payment fails
Jan 2: Some retries are attempted and fail until there is only one retry left for in_1
Jan 7: An invoice in_2 is issued and payment is successful
Jan 14: An invoice in_3 is issued and payment fails
Jan 15: The last retry for in_1 is attempted and fails
In this case, on Jan 15, in_1 fails for the last time and the subscription status will be changed. The status of in_2 does not matter in this case, because the latest invoice is in_3 and in_3 has not been paid. Explicitly, if the subscription status setting is set to “cancel the subscription,” then the subscription is cancelled on Jan 15. If the setting is set to “mark the subscription as unpaid,” then the subscription is marked as unpaid on Jan 15.
To avoid retries from occurring after the next invoice is finalized, the retry window can be set to something smaller or equal to the billing interval. For example, for monthly subscriptions, any retry window <= 1 month will avoid potential overlap.