Combine an Immediate Product Upgrade with an Early Renewal

Allow a customer to upgrade from basic to premium and renew a subscription effective immediately.

Preconditions and Considerations

• The subscription has the status Active.

• The current billing interval has started.

• The renewal is not combined with an alignment of the subscription.

• The product, to which the customer wants to upgrade, has been set up in the Cleverbridge platform.

• 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 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 15th, 2016, a customer purchases a Basic Plan subscription to a photo storage and sharing service for $9.95 annually. The service provides the customer 100 gigabytes of cloud storage.
2. On March 15th, 2017, the customer visits their Self-Service area to switch from a standard to a premium plan for $19.95 annually. The page uses the Get Subscription endpoint to obtain and display the price of the Premium Plan, the next billing date (May 15th, 2018), and other details regarding the subscription.
3. After reviewing this information, the customer confirms this purchase by clicking a Buy Now button on the page. The page uses the Update Subscription Item endpoint to upgrade and renew the customer's subscription to the photo storage and sharing service immediately.
4. The Cleverbridge platform bills the customer the full $19.95 renewal price for the next billing interval, which starts immediately. The remaining two months from the current billing interval are added to the next billing interval, moving the next billing date to May 15th, 2018.

This use case calls the UpdateSubscriptionItem endpoint twice as described below.

Preview of price and next billing date (first call)

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

• Calculate the next billing date if the renewal is made.
• Return the next billing date in the NextBillingDate 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 and renew subscription for another billing interval (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:

• Forward the customer to confirmation page when they click on the Buy Now button. For subscription products, Cleverbridge displays the next payment date, the next payment amount, and a link to cancel 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.