Combine an Immediate Upgrade with an Early Renewal (Monthly to Yearly)

Allow a customer to upgrade from monthly to yearly 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 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 January 1st, 2016, a customer purchases a client's anti-virus subscription for $10 monthly. An annual subscription would have been available for $80 (cost savings of 30%), but the customer is not ready to make that commitment.
  2. On January 15th, 2016, the customer, now fully satisfied with the anti-virus software, visits the clientโ€™s Customer Self-Service area to upgrade to the annual subscription. The page uses the Get Subscription endpoint to obtain and display the price of the annual subscription, the next billing date (February 1st, 2017), 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 anti-virus subscription immediately.
  4. The Cleverbridge platform bills the customer the full $80 price for the next billing interval, which starts immediately. The remaining 16 days from the current billing interval are added to the next billing interval, moving the next billing date to February 1st, 2017.
  5. The customer sees a confirmation page, which is either created by the client or provided by the Subscription API. If the transaction is not successful, the page provided by the API will inform the customer about the next steps, such as updating the payment details in case of a failed payment.

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.
ParameterSet to Value
SubscriptionIdThe unique identifier of the primary subscription.
RunningNumber1 (This subscription has only one item.)
ProductIdThe product ID for the annual plan product (not the current monthly plan product being replaced).
Quantity1
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: true
UpdateActionSee the note below.
TriggerImmediateRenewaltrue

Upgrade by replacing the monthly plan with the yearly plan and renew the 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.

ParameterSet to Value
SubscriptionIdThe unique identifier of the primary subscription.
RunningNumber1 (This subscription has only one item.)
ProductIdThe product ID for the annual plan product (not the current monthly plan product being replaced).
Quantity1
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: false
UpdateActionSee the note below.
TriggerImmediateRenewaltrue

๐Ÿ“˜

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)

๐Ÿšง

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.