Showing results for 
Search instead for 
Did you mean: 

Subscription API ambiguities: payment_failure_threshold, auto_renewal, and total_cycles

New Community Member
Posted on

Hello everyone. My boss and I have discovered some ambiguities in the PayPal Subscriptions API regarding the Plan object's payment_failure_threshold parameter and the relationship between auto_renewal and total_cycles, and we need to resolve these ambiguities before we can continue maintaining our product. I hope I've come to the right place to ask about them.


First of all, our plan's payment_preferences.payment_failure_threshold parameter is set to 0. I set this parameter under the assumption this would cause a subscription to suspend immediately upon failing to bill the user, but my boss saw the following message in the subscription report during testing:


"This profile will be suspended after: No limit failure"


My boss thinks this message implies that a subscription can continue failing to bill infinitely, and it will never be suspended. And to avoid this, payment_failure_threshold should be set to 1 instead of 0.


However, I think there's a reason why payment_failure_threshold defaults to 0 if not explicitly specified, and that PayPal wouldn't be so careless to default to allowing a subscription to last indefinitely if the user can't pay. If we do set payment_failure_threshold to 1, then a user can fail to pay once, and the subscription will continue until the 2nd payment failure, and only then will the subscription end.


Next, we also have different interpretations of the relationship between a subscription's auto_renewal parameter and a plan's billing_cycle.total_cycles parameter.


What my boss thinks is the following:

  • subscription.auto_renewal must be set to true in order for plan.billing_cycle.total_cycles to apply. If subscription.auto_renewal is set to false, it is as if plan.billing_cycle.total_cycles is overridden with the value 1.
  • Therefore, in order to make a subscription last indefinitely, plan.billing_cycle.total_cycles must be set to Infinity. However, its maximum allowed value is 999 (in a monthly subscription, this amounts to roughly 83.25 years)
  • Example: to make a subscription that bills every month and ends after 2 years (24 bills total), auto_renewal must be set to true, and setting it to false after 4 months have passed will make a subscription last for 1 more month and then expire while 19 months still remain.
  • If a user wants the above-described subscription to continue even further than 2 years, the only option is to purchase another subscription once the 2 years have passed.

And what I think is the following:

  • total_cycles applies regardless of whether auto_renewal is set to true or not.
  • Therefore, a subscription will last indefinitely as long as auto_renewal is true. total_cycles is only a formality until auto_renewal is set to false.
  • Example: to make a subscription that bills every month and ends after 2 years (24 bills total), auto_renewal must be set to false, and setting it to true will cause the subscription period to start over once the 2 years are up, effectively making it an infinite subscription.
  • If a user wants the subscription to end after 2 years, just set auto_renewal to false. To end the subscription even earlier than that, the user must cancel the subscription online (which is a different action than setting auto_renewal to false).

The PayPal Subscriptions API documentation does not make it clear which 2 of these 4 interpretations are correct. We cannot continue until these ambiguities are resolved.


Subscription API ambiguities: payment_failure_threshold, auto_renewal, and total_cycles


Hy @ph4631 

I found your question very useful,

Do you now able to explain about the issues which you had,

How can use payment_failure_threshold and auto_renewal in better way,

In documentation they didn't describe something useful other than definition,


Haven't Found your Answer?

It happens. Hit the "Login to Ask the community" button to create a question for the PayPal community.