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 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 May 1st, your customer's Gold subscription renews for $25 for the new monthly billing interval.
2. 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.
3. The customer clicks a link in the promotional email that displays a landing page you created for the promotion.
4. 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.
5. 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: CustomerId or CustomerReferenceId or CustomerEmail.

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).

The 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):

• Active (or 1 for JSON)

• Deactivated (or 3 for JSON)

• Finished (or 4 for JSON)

• Grace (or 5 for JSON)

• Hold (or 6 for JSON)

• New (or 7 for JSON)

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.

📘

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