Change Subscription Renewal Quantity

Change the subscription renewal 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 optional. Before doing so, see Understand Customer Price.
• Use 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.

Description

1. On August 15th, a customer's CRM subscription is automatically renewed for $100 for the new monthly billing interval. The billing amount is based on two subscription items:

• Access: $50
• Users: $50, computed at $5 monthly multiplied by ten users

2. On September 4th, the customer logs into the CRM Management Console and navigates to the Edit Subscription page. This page uses the Get Subscription API endpoint to populate the page with the customer's subscription details, including the current user quantity (10), and the next billing date (September 15th).
3. 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 next billing date (September 15th)

4. The customer selects to update at the next billing date. The edit subscription page uses the Update Subscription Item API endpoint to update the quantity of users in the Cleverbridge platform.
5. On September 15th, the Cleverbridge platform automatically bills the customer $125 for the monthly renewal of the subscription, which reflects $50 for access and $75 for 15 users.

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

Retrieve the Quantity of Users (first call)

To retrieve the current subscription item quantity:

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.

3. Retrieve the current quantity for the Users subscription item from this instance of the array.

Update Subscription Item Price (second call)

Set the parameters in the Update Subscription Item API call to the values listed in the table.

📘

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.

🚧

Important

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

Illustration