Retain Customer with a Discount

You can offer a discount to your customers to improve customer retention. The following contains relevant information about this use case:

Preconditions and Considerations

  • The subscription's status is Active.

  • The coupon code was 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 January 1st, a customer's Enterprise Hosting subscription renews for $120 for the new monthly billing interval.
  2. On January 20th, the customer experiences slow page load times that adversely affect the customer's business. The customer calls the client's customer service department and threatens to cancel the subscription.
  3. Your customer service representative accesses a customer subscription page using an internal support application that uses the Get Subscription API endpoint to return details for the customer's active subscriptions.
  4. To retain the customer's business, the customer service representative offers to discount the customer's Enterprise Hosting subscription for the next six months. The customer agrees to this.
  5. The customer service representative uses an internal billing adjustment tool to apply a specific coupon code (that had been set up in the Cleverbridge platform) to the subscription. This tool uses the Update Subscription Item API endpoint to update the customer's subscription details in the Cleverbridge platform.
  6. On February 1st, the next monthly renewal date, the Cleverbridge platform automatically bills the customer at the discounted price of $60. The 50% discount is applied to subsequent renewal billings for five additional monthly billing intervals.

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 for the customer's subscription.
RunningNumber1 (This subscription has only one item.)
ProductIdProduct ID for the current Enterprise Hosting product associated with the subscription item.
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: false
UpdateActionSee the note below.
CouponCodeA coupon code previously set up in the Cleverbridge platform.



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)