Retain Customer by Increasing the Subscription Billing Interval

Change a subscription’s billing interval from shorter to longer, effective on the next billing date.

Preconditions and Considerations

  • The subscription has the status Active.

  • The subscription contains only a single item.

  • A product that renews annually has been set up in the Cleverbridge platform.

  • Using the Update Subscription Item API endpoint to change the billing interval of a subscription is only supported for single-item subscriptions (which is the most common type of subscription), and only effective at the time of the next billing date. Otherwise, when one subscription item is replaced with another, the original and the replacement items must have the same currency and billing interval.

  • Changes made by this function, including the price and/or quantity, apply to all future billing events unless changed subsequently.

  • Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.

  • Use of the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.

  • When you add a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

For more information on which API endpoint to use, see Guidelines for When to Use UpdateSubscriptionItem vs. UpdateSubscriptionItemPrice.


  1. On May 8th, a customer clicks through an email reminder to manually renew an annual anti-virus subscription, which has a monthly billing interval, by the July 1st renewal date. The email redirects the customer to a landing page that displays the following options:
Choose One PlanMonthly CostAnnual Cost
Current Plan: Monthly Renewal
$100 billed monthly
Best Deal (save 25%): Annual Renewal
$900 billed annually
  1. The customer selects the annual renewal option and then clicks a button to proceed. The page uses the Update Subscription Item endpoint to change the subscription from one that has a monthly billing interval to one that has an annual billing interval.
  2. On July 1st, the Cleverbridge platform automatically bills the customer $900 for the next annual billing interval.

To update the customer's subscription data in the Cleverbridge platform, set the parameters in the Update Subscription Item API call to the values listed in the table.

ParameterSet to Value
SubscriptionIdThe unique identifier of the primary subscription.
RunningNumber1 (to change the subscription billing interval, the subscription can only have one item.)
ProductIdProduct ID for the new product (in this use case, it is the ID of the product with an annual billing interval).
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: false
UpdateActionSee the note below.



The UpdateAction parameter is currently used for documentation and tracking only. The value set does not affect transaction processing.

The supported values are as follows:

  • For upgrades, set the parameter to upgrade (or 1 for JSON)
  • For downgrades, set the parameter to downgrade, (or 2 for JSON)
  • For all other changes, set the parameter to update (or 0 for JSON)

Usage Notes

Changing the billing interval of a customer’s subscription is achieved by setting up two products in the Cleverbridge platform, one for each of the two billing intervals. Usually, these products are functionally identical to each other, but are not required to be.


Although not utilized in this use case, the following options are also available:

  • Reduce the subscription billing amount by applying a discount coupon that was set up in the Cleverbridge platform.
  • Set a customized per-quantity price for the subscription item.



Obtain the customer's consent for changes to subscriptions. For more information, see Best Practices: Obtain Customer Consent.