Increase Subscription Quantity Immediately

You can increase subscription quantity or volume, effective immediately. The following contains relevant information about this use case:

Preconditions and Considerations

  • The customer has a subscription with an Active status.
  • Any changes made apply to current and all future billing events unless modified subsequently.
  • Using the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.

Description

A client offers a DiamondCRM subscription product that contains a single item, Users, billed at $50 monthly, and multiplied by the number of users specified by the customer.

  1. On September 1st, a customer logs into the DiamondCRM administration console and navigates to the Edit Subscription page. This page uses the Get Subscription API endpoint to display the customer's subscription details, including the Users subscription item, which displays the quantity ten.
  2. The customer changes the user quantity to 15 in the entry field provided. The customer must choose between two options before the change can be submitted:
  • Update immediately
  • Update at the next billing date (September 27th)
  1. The customer selects to update the subscription immediately. The Edit Subscription page uses the Increase Subscription Item Quantity API endpoint to calculate the pro-rated price for the five additional users from September 1st through September 27th. The price displays with a message that the customer will be billed immediately for the pro-rated amount shown.
  2. After reviewing this message, the customer confirms the update. The Edit Subscription page uses the Increase Subscription Item Quantity API endpoint to update the number of users in the Cleverbridge platform.
  3. The Cleverbridge platform automatically bills the customer the pro-rated amount for the five additional users for the remainder of the current billing interval.
  4. On September 27th, the Cleverbridge platform automatically bills the customer $750 for the next monthly billing interval. This is based on the user quantity of 15.

Retrieving the Quantity of Users

This use case assumes that the current subscription item quantity is being retrieved for display. To do so:

  1. Call the Get Subscription API endpoint.
  2. In the SubscriptionItem array data returned in the response, locate the single instance in the array for which both of the following statements are true:
  • RunningNumber matches the running number of the subscription item for which the quantity is needed.
  • The IsCurrent parameter is true.
  1. Retrieve the current quantity for the Users subscription item from this instance of the array.

This use case calls the Update Subscription Item API endpoint twice as described below:

Preview of pro-rated billing amount (first call)

If the API call is formatted as described below, it will:

  • Calculate the pro-rated price to be billed if the five additional users are added.
  • Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
  • Not change any data in the Cleverbridge system.
ParameterSet to Value
SubscriptionIdThe unique identifier for the subscription.
RunningNumber1 (This subscription has only one item.)
ProductIdProduct ID for the user's subscription item.
Quantity15 (The new quantity.)
AlignmentSettingsAlignToCurrentInterval: true
GetCustomerPricePreviewOnly: true
UpdateActionSee the note at the end of this section.

Upgrade by increasing quantity (second call)

If the API call is formatted as described below, it will update the customer's subscription data in the Cleverbridge platform.

ParameterSet to Value
SubscriptionIdThe unique identifier for the subscription.
RunningNumber1 (This subscription has only one item.)
ProductIdProduct ID for the user's subscription item.
Quantity15 (The new quantity.)
AlignmentSettingsAlignToCurrentInterval: true
GetCustomerPricePreviewOnly: false
UpdateActionSee the note at the end of this section.

Quantity Increase by Next Billing Date

👍

Tip

To increase the subscription quantity effective by the next billing date:

  • call the Update Subscription Item API endpoint twice, as described above.
  • set both sub-parameter values in the AlignmentSettingsto falsein the second call. The customer is billed the pro-rated price for the additional users on the next billing date.

📘

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)

Options

Although not utilized in this use case, the following option is also available:

  • Apply a discount coupon that was set up in the Cleverbridge platform to reduce the price of the Users subscription item.

👍

Tip

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

Illustration

sub bill change props change qty immediately