Docs
Chargebee automatically renews a subscription based on the billing interval set for the plan. By default, the subscriptions renew indefinitely until they are canceled manually or canceled due to dunning. You can control the number of renewals (i.e, the lifetime of the subscription) by setting the Number of Billing Cycles.
The lifetime of a subscription can be controlled by specifying the Number of Billing cycles while creating the subscription. It is internally stored as the "remaining billing cycles" for that subscription.
On each term start, the remaining billing cycles attached to a particular subscription would be reduced automatically. So, the subscriptions would continue to renew till the remaining billing cycles reduce to 0. Once it becomes 0, the subscription will be moved to non-renewing state as it is not going to renew anymore. Hence, the subscription will get canceled on next billing date/time.
Number of Billing cycles can be configured in the Plan level as well. The value configured at the plan level will be taken if it is not explicitly specified while creating the subscription.
The lifetime of a subscription can be modified anytime after it is created.
What happens when a subscription's plan is changed?
When a subscription's plan is changed, then the remaining billing cycles is reset based on the new plan's number of billing cycles. If the new plan does not have the number of billing cycles set, then the subscription will renew forever.
You could also override the new plan's number of billing cycles by explicitly specifying the value while changing the subscription.
When is the remaining billing cycle decremented?
The phrase each subscription term start is important to understand the behavior of the remaining billing cycles. On each term start , the remaining billing cycles attached to a particular subscription would be reduced automatically.
When a subscription is created with a plan that has no trial, the remaining billing cycles is reduced by one immediately as it is the start of a new subscription term.
Plan's number of billing cycles = 5.
Subscription's remaining billing cycles after creation = 4
In case the subscription has a trial period, the remaining billing cycles is reduced only at the activation after the trial ends.
Plan's number of billing cycles = 5.
Subscription's remaining billing cycles after creation = 5
Subscription's remaining billing cycles after activation = 4
On renewal, the current subscription term ends and a new term is started. This results in the remaining billing cycles to reduce by one.
Subscription's remaining billing cycles before renewal = 4
Subscription's remaining billing cycles after renewal = 3
When the plan associated with the subscription is changed mid-term, the remaining billing cycles is reset (as explained previously in this document) but it is not decremented immediately as current term is continued. It will be decremented only at the renewal when the next term starts.
New Plan's number of billing cycles = 7.
Subscription's remaining billing cycles before change = 4
Subscription's remaining billing cycles after change = 7
Subscription's remaining billing cycles after renewal = 6
In case the new plan has a different billing period (eg. quarterly) when compared to the currently associated plan (eg. monthly), the current term is ended and a new subscription term with the different period is started for that subscription. Hence in this case the remaining billing cycles is reduced by one immediately during the change.
New Plan's number of billing cycles = 7.
Subscription's remaining billing cycles before change = 4
Subscription's remaining billing cycles after change = 6
When a subscription is scheduled to be canceled, the value of remaining billing cycles will be set to zero. If this operation is performed when the subscription is in active state, the state will be changed to non renewing. However, in-trial subscriptions would remain so before changing state to cancelled at the end of the term.
In case the scheduled cancellation is removed for the subscription, the number of billing cycles will be taken from plan. However, the number of billing cycles can be specified explicitly when removing.
You can give customers the option to revoke scheduled cancellations and extend their subscription. Learn more about this feature here.
When a reactivation happens, the remaining billing cycles will be reset to plan's number of billing cycles minus one as the subscription activation has been reset and a new subscription term has started.
Whereas for the in-term reactivation, the number of billing cycles will not be changed.
Articles & FAQ