Upgrade a Subscription Effective Next Billing Date
Allow a customer to upgrade a subscription effective with the next billing date.
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 is 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
CustomerPriceparameter in the API response is optional. Before doing so, see Understand Customer Price.
- Use of the
AlignmentSettingsparameter 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.
- On May 1st, your customer's Gold subscription renews for $25 for the new monthly billing interval.
- On May 23rd, you send a promotional email to your Gold customers, offering a 20% discount if the upgrade is made within the next five days to your Platinum-level subscription. This discount offers the Platinum subscription for $40 instead of $50 monthly.
- The customer clicks a link in the promotional email that displays a landing page you created for the promotion.
- The customer enters the subscription ID and clicks the Buy Now button to accept the upgrade. The landing page calls the following endpoints:
- Get Subscriptions for Customer to obtain the customer's current subscription details.
- Update Subscription Item to complete the upgrade to the Platinum subscription.
- On June 1st, the Cleverbridge platform automatically bills the customer the discounted price of $40 for the Platinum subscription's new monthly interval.
This use case requires two calls as described below:
Obtain the customer's current subscription details (first call)
To call the Get Subscriptions for Customer endpoint, pass one (and only one) of the following parameters:
If your company is able to securely identify a customer prior to an order, then you can pass your own unique customer identifier to Cleverbridge, and Cleverbridge will store it as
CustomerReferenceId for your subsequent use in qualifying certain API endpoint calls (including this one).
Subscriptionstatus parameter is optional. If it is blank, information on all subscriptions for the specified customer is returned. The
Subscriptionstatus parameter takes the following string values (and returns a corresponding integer in a JSON response):
Complete the upgrade to the Platinum subscription (second call)
Call the Update Subscription Item endpoint as formatted below to update the customer's subscription data in the Cleverbridge platform.
|Parameter||Set to Value|
|The unique identifier of the primary subscription.|
|Product ID for the platinum product (not the current gold product being replaced).|
|See the note below.|
UpdateActionparameter 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
- For downgrades, set the parameter to
- For all other changes, set the parameter to
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.
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.
Updated about 2 months ago