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 behaviour 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:
1 Jan: An invoice in_1
is issued and payment fails
2 – 30 Jan: Some retries are attempted and fail until there is only one retry left for in_1
1 Feb: An invoice in_2
is issued and payment is successful
10 Feb: 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:
1 Jan: An invoice in_1
is issued and payment fails
2 Jan: Some retries are attempted and fail until there is only one retry left for in_1
7 Jan: An invoice in_2
is issued and payment is successful
14 Jan: An invoice in_3
is issued and payment fails
15 Jan: The last retry for in_1
is attempted and fails
In this case, on 15 Jan, 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 15 Jan. If the setting is set to "mark the subscription as unpaid", then the subscription is marked as unpaid on 15 Jan.
To avoid retries from occurring after the next invoice is finalised, 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.