Customize Subscription Renewal Price and Quantity

Customize a subscription's renewal price and quantity for a customer.

The following contains relevant information about this use case:

Preconditions and Considerations

  • ~~The subscription has the status Active.
  • Any changes made, including the price and/or quantity, apply to all future billing events unless modified subsequently.
  • Use of the CustomerPrice parameter in the API response is required. Before doing so, see Understand Customer Price.
  • Using the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.

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


  1. On April 8th, a customer receives a reminder to manually renew their annual subscription by the June 1st renewal date. They contact your company’s account manager, state that they might be interested in increasing the number of subscription licenses from 100 to 300, and ask for “the best price possible” if they do so.
  2. The account manager in your organization accesses an intranet application that uses the Get Subscription API endpoint to retrieve details for the customer’s subscription.
  3. You offer to reduce the customer’s per-license price from 29.95€ to 24.95€ at the time of renewal, contingent upon the customer renewing the subscription with a quantity of 300 licenses.
  4. The customer consents to the proposed changes. The account manager accesses an internal application that uses the Update Subscription Item Price API endpoint to change the price per license and the quantity of licenses, effective with the next billing date.
  5. On June 1st, the Cleverbridge platform automatically bills the customer for the annual renewal at the new subscription per-license price and quantity.

This use case calls the Get Subscription and the Update Subscription Item Price API endpoints as described below:

Retrieve Subscription Data (first call)

Retrieve the customer’s current subscription item quantity & price by calling the Get Subscription API endpoint.

Update Subscription Item Price & Quantity (second call)

To change the subscription in the Cleverbridge platform, call the Update Subscription Item Price endpoint with the following parameter values:

ParameterSet to Value
SubscriptionIdThe unique identifier of the subscription.
RunningNumber1 (it is assumed that the seats item is the only item in the subscription).
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: false
CustomerPriceCurrencyId: CHF
IsGross: true
Value: 24.95
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)