Co-Term Subscription Items (Shorten Billing Interval of Additional 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 shorten the billing interval of the new seat so that all subscriptions co-term, integrate the following flow into your system:

Step 1: Show customer pro-rated price of additional seat

If a customer would like to purchase an additional license and shorten the billing interval of the additional 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 pro-rated additional license for the remainder of the current billing interval. 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 to true in the AlignmentSettings argument to generate the pro-rated cost of shortening the billing interval of the 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 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 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-01-01T12:59:59.111100",
      ...
    }],				
  ...
  }
}