Retain Customer by Decreasing the Subscription Billing Interval

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

Preconditions and Consideration

  • The subscription has the status Active.

  • The subscription contains only a single item.

  • 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 April 15th, a customer receives a reminder to manually renew an annual subscription for $15,000 by the June 1st renewal date. Due to a large increase in subscription seats purchased since last year, the customer does not currently have the budget to renew for another year. They contact the client’s account manager to see what can be done to solve this problem.
  2. The client’s account manager enters the customer’s email address into an intranet application that uses the Get Subscriptions for Customer API endpoint to retrieve details for the customer’s subscriptions.
  3. Realizing that changing the billing interval for the customer’s subscription would smooth out the cash flow impact of renewing, the client proposes changing the billing interval of the customer’s subscription from annually to monthly. If the customer agrees, then they would owe $1,800 on June 1st instead of $15,000.
  4. The customer agrees to the proposal and consents to the changes to their subscription. The account manager accesses an internal application that uses the Update Subscription Item API endpoint to change the subscription from one with an annual billing interval to one with a monthly billing interval.
  5. On June 1st, the Cleverbridge platform automatically bills the customer for the $1,800 monthly annual renewal at the new subscription per-seat price and quantity.

Retrieve the customer's current subscription details (first call)

To call the Get Subscriptions for Customer endpoint, pass one (and only one) of the following parameters: CustomerId or CustomerReferenceId or CustomerEmail.

If your company is able to securely identify a customer prior to an order, then you can pass your own unique customer identifier to Cleverbridge, and Cleverbridge will store it as CustomerReferenceId for your subsequent use in qualifying certain API endpoint calls (including this one).

The Subscriptionstatus parameter is optional. If it is blank, information on all subscriptions for the specified customer is returned. The Subscriptionstatus parameter takes the following string values (and returns a corresponding integer in a JSON response):

  • Active (or 1 for JSON)

  • Deactivated (or 3 for JSON)

  • Finished (or 4 for JSON)

  • Grace (or 5 for JSON)

  • Hold (or 6 for JSON)

  • New (or 7 for JSON)

Change the annual subscription to a monthly subscription (second call)

Call the Update Subscription Item API endpoint to update the customer's subscription data in the Cleverbridge platform.

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 a monthly 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 option is 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.