Overview

This guide shows you how to upgrade a customer's subscription plan using the Update Subscription Item API endpoint.

Use Case

A Cloudify Gold customer wants to upgrade to Cloudify Platinum.
Your page calls the Update Subscription Item endpoint to show a pro-rated price. The customer will pay for the new plan for the remainder of the current billing interval.
The customer confirms the previewed price.
The Update Subscription Item endpoint is called again with updated AlignmentSettings to process the upgrade.
Cleverbridge processes the upgrade using the payment details stored in our database.
After the payment is received, Cleverbridge sends a PaidOrderNotification to your configured notification endpoint.

Implement Update Subscription Item

Before you start

Make sure that:

You have credentials for the Cleverbridge REST API.
You know the customer's SubscriptionId and the ProductId of the plan they're upgrading to.
The customer has an active subscription eligible for upgrade.
You can receive PaidOrderNotification notifications.

Step 1: Show customer price of upgrade

If a customer would like to upgrade, call the Update Subscription Item API endpoint to generate a preview of the pro-rated price. The customer will pay for the new plan for the remainder of the current billing interval.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	`AlignToCurrentInterval: true` `ExtendInterval: true` `GetCustomerPricePreviewOnly: true`	Set `GetCustomerPricePreviewOnly` to `true` to preview the upgrade cost without changing any data in the Cleverbridge system. Set to `false` to process the upgrade.
GenerateMail	bool	No	`false`	Set to `false` when previewing the price so no email is sent. Set to `true` when processing the upgrade to send the customer a confirmation email.
ProductId	int	Yes	294581	Product ID of the plan the customer is upgrading to.
Quantity	int	Yes	1	The quantity of the new subscription item.
RunningNumber	int	Yes	1	The running number of the subscription item being upgraded.
SubscriptionId	str	Yes	S67203942	The unique identifier of the subscription.
UpdateAction	str	Yes	`Upgrade`	Identifies the type of update being made, for reporting purposes.

Request

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
    "SubscriptionId": "S67203942",
    "ProductId": 294581,
    "Quantity": 1,
    "GenerateMail": false,
    "UpdateAction": "Upgrade",
    "RunningNumber": 1,
    "AlignmentSettings": {
      "AlignToCurrentInterval": true,
      "ExtendInterval": true,
      "GetCustomerPricePreviewOnly": true
    }
  }'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S67203942",
  "ProductId": 294581,
  "Quantity": 1,
  "GenerateMail": False,
  "UpdateAction": "Upgrade",
  "RunningNumber": 1,
  "AlignmentSettings": {
    "AlignToCurrentInterval": True,
    "ExtendInterval": True,
    "GetCustomerPricePreviewOnly": True
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/updatesubscriptionitem", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'rest.cleverbridge.com',
  'path': '/subscription/updatesubscriptionitem',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "SubscriptionId": "S67203942",
  "ProductId": 294581,
  "Quantity": 1,
  "GenerateMail": false,
  "UpdateAction": "Upgrade",
  "RunningNumber": 1,
  "AlignmentSettings": {
    "AlignToCurrentInterval": true,
    "ExtendInterval": true,
    "GetCustomerPricePreviewOnly": true
  }
});

req.write(postData);

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/updatesubscriptionitem")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")

  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"SubscriptionId\": \"S67203942\",\n    \"ProductId\": 294581,\n    \"Quantity\": 1,\n    \"GenerateMail\": false,\n    \"UpdateAction\": \"Upgrade\",\n    \"RunningNumber\": 1,\n    \"AlignmentSettings\": {\n      \"AlignToCurrentInterval\": true,\n      \"ExtendInterval\": true,\n      \"GetCustomerPricePreviewOnly\": true\n    }\n  }")
  .asString();

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

Response

{
    "AlignmentCustomerGrossPrice": 131.65,
    "AlignmentCustomerNetPrice": 110.63,
    "AlignmentCustomerVatPrice": 21.02,
    "NextBillingCustomerGrossPrice": 143.42,
    "NextBillingCustomerNetPrice": 120.52,
    "NextBillingCustomerVatPrice": 22.9,
    "NextRenewalCustomerGrossPrice": 143.42,
    "NextRenewalCustomerNetPrice": 120.52,
    "NextRenewalCustomerVatPrice": 22.9,
    "PriceCurrencyId": "EUR",
    "ResultMessage": "OK"
}

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 processes the upgrade using the payment details that we have stored in our database. A confirmation email is sent to the customer.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	`AlignToCurrentInterval: true` `ExtendInterval: true` `GetCustomerPricePreviewOnly: false`	Set `GetCustomerPricePreviewOnly` to `true` to preview the upgrade cost without changing any data in the Cleverbridge system. Set to `false` to process the upgrade.
GenerateMail	bool	No	`true`	Set to `false` when previewing the price so no email is sent. Set to `true` when processing the upgrade to send the customer a confirmation email.
ProductId	int	Yes	294581	Product ID of the plan the customer is upgrading to.
Quantity	int	Yes	1	The quantity of the new subscription item.
RunningNumber	int	Yes	1	The running number of the subscription item being upgraded.
SubscriptionId	str	Yes	S67203942	The unique identifier of the subscription.
UpdateAction	str	Yes	`Upgrade`	Identifies the type of update being made, for reporting purposes.

Request

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
    "ProductId": 294581,
    "RunningNumber": 1,
    "SubscriptionId": "S67203942",
    "UpdateAction": "Upgrade",
    "Quantity": 1,
    "GenerateMail": false,
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false,
        "ExtendInterval": true
    }
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S67203942",
  "ProductId": 294581,
  "Quantity": 1,
  "GenerateMail": True,
  "UpdateAction": "Upgrade",
  "RunningNumber": 1,
  "AlignmentSettings": {
    "AlignToCurrentInterval": True,
    "ExtendInterval": True,
    "GetCustomerPricePreviewOnly": False
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/updatesubscriptionitem", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'rest.cleverbridge.com',
  'path': '/subscription/updatesubscriptionitem',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "SubscriptionId": "S67203942",
  "ProductId": 294581,
  "Quantity": 1,
  "GenerateMail": true,
  "UpdateAction": "Upgrade",
  "RunningNumber": 1,
  "AlignmentSettings": {
    "AlignToCurrentInterval": true,
    "ExtendInterval": true,
    "GetCustomerPricePreviewOnly": false
  }
});

req.write(postData);

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/updatesubscriptionitem")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"SubscriptionId\": \"S67203942\",\n    \"ProductId\": 294581,\n    \"Quantity\": 1,\n    \"GenerateMail\": true,\n    \"UpdateAction\": \"Upgrade\",\n    \"RunningNumber\": 1,\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": true,\n        \"ExtendInterval\": true,\n        \"GetCustomerPricePreviewOnly\": false\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 131.65,
    "AlignmentCustomerNetPrice": 110.63,
    "AlignmentCustomerVatPrice": 21.02,
    "NextBillingCustomerGrossPrice": 143.42,
    "NextBillingCustomerNetPrice": 120.52,
    "NextBillingCustomerVatPrice": 22.9,
    "NextRenewalCustomerGrossPrice": 143.42,
    "NextRenewalCustomerNetPrice": 120.52,
    "NextRenewalCustomerVatPrice": 22.9,
    "PriceCurrencyId": "EUR",
    "ResultMessage": "OK"
}

Step 3: Receive the PaidOrderNotification

Cleverbridge processes the charge initiated in Step 2 asynchronously. After Cleverbridge receives the payment, it sends a PaidOrderNotification to your configured notification endpoint.

When you receive the notification:

Verify that meta.type is PaidOrderNotification.
Use purchaseId to identify the paid order and items[].recurringBilling.subscriptionId to correlate it with the subscription updated in Step 2.
Use the subscription and order information to update connected systems such as your CRM or ERP. Grant or update the applicable entitlement.

Design your notification handler to process retries safely so that receiving the same notification more than once does not create duplicate updates.

PaidOrderNotification parameters

Parameter	Definition
`subscriptionId`	Unique ID of the Cleverbridge subscription.
`intervalNumber`	Number of the billing interval associated with the subscription item.
`nextBillingDate`	Date on which the subscription is currently scheduled to renew. When the subscription item is aligned to the current interval, it follows the existing renewal schedule.
`purchaseId`	Unique ID of the paid order. Use this to identify the order in your systems.
`meta.type`	Identifies the notification type. Confirm this equals PaidOrderNotification before processing.

{
  "meta": {
    "type": "PaidOrderNotification"
  },
  "purchaseId": 123456789,
  "items": [
    {
      "recurringBilling": {
        "subscriptionId": "S67203942",
        "intervalNumber": 1,
        "nextBillingDate": "2026-10-09T14:47:34.857671"
      }
    }
  ]
}