Check out the new features, minor fixes, and updates we've made to our platform and APIsChangelog
Home >

Update Subscription Item

Purpose

The UpdateSubscriptionItem API function is used to:

This function also supports the optional ability to update the price for the item. If no price is specified in the function call, then this function does not change the CustomerPrice value that is currently stored for the subscription on the cleverbridge platform.

Guidelines for When to Use UpdateSubscriptionItemPrice vs. UpdateSubscriptionItem

It's possible to use either the UpdateSubscriptionItem or the UpdateSubscriptionItemPrice functions if the only subscription item properties to be changed are the price, the quantity, or both. The following guidelines should be kept in mind when making this decision:

  • UpdateSubscriptionItemPrice should be used for new development in which only the subscription item’s price and (optionally) quantity will change.
  • UpdateSubscriptionItem should be used for new development or for modifying existing client code in cases where subscription data in addition to price and (optionally) quantity will be changed.

Considerations

The following are considerations for this function:

  • Using this API function 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 Understanding Customer Price.
  • Use of the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, see Alignment Settings.
  • If a client adds a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

Required Parameter Settings by Use Case

Certain parameters for use cases that use this function require specific values. Set the values for the parameters as shown in the tables below.

Note

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)