Combine Upgrade with Early Renewal (Basic to Premium)

A great way to grow your revenue is to convince your current customers that they should not only renew, but upgrade to a premium version of your product. This makes customer churn less likely. To enable customers to upgrade to premium plans and renew early, integrate the following flow into your system:

Step 1: Show customer price of upgrade and immediate renewal

If a customer has a single-item subscription and would like to upgrade and start a new billing interval immediately, call the Update Subscription Item API endpoint to generate a preview of the price that the customer will pay for the new plan. In the API call, do the following:

Submit the ProductId that belongs to the premium product.
Set AlignToCurrentInterval and GetCustomerPricePreviewOnly to true in the AlignmentSettings argument and set GenerateMail to false to generate a preview that will not be processed or communicated via email.
Set UpdateAction to Upgrade for reporting purposes.
Set ExtendInterval to true to apply the new subscription interval.

Example

When a customer buys a standard product and pays $99.95 for a yearly subscription and then immediately agrees to upgrade to a premium product that costs $150 yearly, the call to generate a preview the price for the upgraded plan looks as follows:

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": true,
      "ExtendInterval": true,
      "GetCustomerPricePreviewOnly": true
    },
    "GenerateMail": false,
    "ProductId": 123456,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "UpdateAction": "Upgrade"
  }'

For more information about the AlignmentSettings argument, see Alignment Settings.

Step 2: Process upgrade for customer

After the customer confirms the previewed price, set GetCustomerPricePreviewOnly to false in the AlignmentSettings argument and set GenerateMail to true. Call the Update Subscription Item API endpoint again. Cleverbridge will process the upgrade using the payment details that we have stored in our database and send a confirmation email to the customer.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": true,
      "ExtendInterval": true,
      "GetCustomerPricePreviewOnly": false
    },
    "GenerateMail": true,
    "ProductId": 123456,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "UpdateAction": "Upgrade"
  }'

You'll receive the following response as confirmation that the price has been calculated and the interval aligned for the upgraded plan:

{
  "UpdateSubscriptionItemResponse": {
    "ResultMessage": "OK",
    "AlignmentCustomerGrossPrice": "50.32",
    "AlignmentCustomerVatPrice": "42.29",
    "AlignmentCustomerNetPrice": "8.03",
    "NextBillingCustomerGrossPrice": "150",
    "NextBillingCustomerVatPrice": "126.05",
    "NextBillingCustomerNetPrice": "23.95",
    "PriceCurrencyId": "USD",
    "_xmlns": "http://api.cleverbridge.com/datacontract"
  }
}

Step 3: Cleverbridge sends you a PaidOrderNotification

Cleverbridge sends you a PaidOrderNotification, which contains information that allows you to update your local ecosystem (CRM, ERP, etc.). It includes:

Parameter	Description
`subscriptionID`	the Cleverbridge subscription ID
`renewalType`	whether the subscription has an automatic or manual renewal type
`intervalNumber`	the current billing interval, which for renewals is always `1` or more
`nextBillingDate`	the next billing date is calculated based on your product settings

{  
  "meta": {  
    "type": "PaidOrderNotification",  
    "date": "2019-03-19T14:47:34.857671",  
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"  
  },  
  "purchaseId": 123456789,  
  ...  
  "items": [{  
    ...  
    "recurringBilling": {  
      "subscriptionId": "S12345678",  
      ...  
      "intervalNumber": 1,  
      ...  
      "nextBillingDate": "2020-03-19T14:47:34.857671",  
      ...  
      "renewalType": "Automatic"  
      ...  
    }],				  
  ...  
  }  
}