Co-Term Subscription Items (Extend Billing Interval of Original Seat)

If your customers pay based on the number of individuals using a product or service, a great way to grow your revenue is to enable customers to add seats or users. To enable customers to add a seat and extend the billing interval of the existing seat(s) so that all subscriptions co-term, integrate the following flow into your system:

Step 1: Show customer price of additional seat and extension of original seat

If a customer would like to purchase an additional license and extend the billing interval of the existing license so that the two licenses co-term, call the Update Subscription Item API endpoint to generate a preview of the full price that the customer will pay for the additional license plus the pro-rated price of the extension. In the API call, do the following:

• Enter the new Quantity of licenses that the customer will have after the completion of this transaction (existing license + additional license).
• Set AlignToCurrentInterval and ExtendInterval to true in the AlignmentSettings argument to generate the pro-rated cost of extending the billing interval of the original license, plus the cost of adding an additional license.
• Set 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 Update for reporting purposes.

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": 2,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": false,
    "UpdateAction": "Update"
  }'

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

Step 2: Process change 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 transaction 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": 2,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": false,
    "UpdateAction": "Upgrade"
  }'

Step 3: Cleverbridge sends you a PaidOrderNotification

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

{  
  "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",  
      ...  
    }],				  
  ...  
  }  
}