Upgrade a Subscription Immediately

Allow a customer to upgrade a subscription effective immediately. Calculate the pro-rated price for an immediate subscription upgrade.

Preconditions and Considerations

• The subscription has the status Active.
• The product to which the customer wants to upgrade has been set up in the Cleverbridge platform.
• Both products have the same billing interval.
• Using this 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 current and 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.

Description

1. On January 1st, a customer uses the Cleverbridge checkout process to purchase a Basic Plan subscription to a photo storage and sharing service for $9.95 annually. The service provides the customer with 100 gigabytes of cloud storage.
2. On January 15th, the customer visits your company’s update page to upgrade to the Premium Plan (unlimited storage) for $19.95 annually. The page uses the Update Subscription Item endpoint to calculate the pro-rated price difference between the Basic Plan and the Premium Plan for the remainder of the current billing interval.
3. The upgrade page displays the pro-rated price to the customer, who proceeds with the upgrade. Your company's landing page uses the Update Subscription Item endpoint to complete the upgrade by updating subscription information in the Cleverbridge platform.
4. The Cleverbridge platform automatically bills the customer the pro-rated upgrade price for the remaining six months of the current billing interval.
5. On January 1st of next year, the Cleverbridge platform automatically bills the customer the full $19.95 renewal price for the Premium Plan.

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

Preview of pro-rated billing amount (first call)

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

• Calculate the pro-rated price to be billed if the upgrade is made.
• 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.

Upgrade by replacing the basic plan with the premium plan (second call)

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

📘

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:

• Reduce the price of the Paid subscription by applying a discount coupon that was set up in the Cleverbridge platform. This discount is applied to all future billings of the subscription.

🚧

Important

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

Manage upgrades and downgrades. For more information, see Best Practices: Manage Upgrades and Downgrades.

Illustration