Overview

This guide shows you how to implement the Increase Subscription Item Quantity endpoint to increase subscription user quantity, effective immediately.

Use case

Cloudify customer with 10 subscription users wants to increase user quantity within the same billing period.
Customer chooses to increase the user quantity.
Increase Subscription Item Quantity endpoint is used to calculate the pro-rated price for the 15 additional users.
After reviewing this message, the customer confirms the update. Increase Subscription Item Quantity endpoint is used again to proceed with the update.
The Cleverbridge platform automatically bills the customer the pro-rated amount.

Implement the API endpoint

Before you start

Make sure that:

The customer has a subscription with an Active status.

🚧
Important
Get the customer's consent before making changes to a subscription.
To avoid chargebacks and customer inquiries, it is also essential that you coordinate all price increases with Client Experience.
In the European Economic Area (EEA), Strong Customer Authentication (SCA) is required for recurring electronic payments when the amount changes. This means that some of your customers will have to authenticate their payment, which in turn might impact the renewal success rate.
For more information, see Best Practices: Obtain Customer Consent.

Step 1: Retrieve the Quantity of Users

Call the Get Subscription endpoint to retrieve the current number of users from the Quantity parameter in the Items array.

Parameter	Type	Required	Example	Notes
SubscriptionId	str	Yes	S67661151	The unique identifier of the subscription.

Request

curl --location 'https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S68574751' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS'

import http.client

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = ''
headers = {
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("GET", "/subscription/getsubscription?subscriptionId=S68574751", 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': 'GET',
  'hostname': 'rest.cleverbridge.com',
  'path': '/subscription/getsubscription?subscriptionId=S68574751',
  'headers': {
    '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);
  });
});

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.get("https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S68574751")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .asString();

Response

{
    "Subscription": {
        "CustomerCurrencyId": "USD",
        "CustomerId": 159215775,
        "CustomerReferenceId": "skTI6EGSpGU1kODfm86bGsERjB5DGORw8Xj8wTGA",
        "CustomerReferenceNo": "",
        "EndDate": null,
        "GracePeriodDays": 0,
        "Id": 68574751,
        "IntervalDayCount": 0,
        "IntervalMonthCount": 1,
        "BillingIntervalDayCount": 0,
        "BillingIntervalMonthCount": 0,
        "Items": [
            {
                "Couponcode": "",
                "DeactivationDate": null,
                "EndDate": null,
                "IsCurrent": true,
                "LastIntervalNo": 0,
                "NextBillingCurrencyId": "USD",
                "NextBillingCustomerGrossPrice": 800.0,
                "NextBillingCustomerNetPrice": 672.27,
                "NextBillingCustomerVatPrice": 127.73,
                "NextRenewalCustomerGrossPrice": 800.0,
                "NextRenewalCustomerNetPrice": 672.27,
                "NextRenewalCustomerVatPrice": 127.73,
                "ProductId": 293160,
                "ProductName": "Cloudify M",
                "ProductNameExtension": "",
                "PromotionId": null,
                "Quantity": 10,
                "RecurrenceCount": null,
                "RunningNo": 1,
                "StartDate": "2026-04-23T15:57:14.106747",
                "Status": 1,
                "SubscriptionId": 68574751,
                "SubscriptionPurchaseItems": [
                    {
                        "PurchaseId": 538988784,
                        "PurchaseItemRunningNo": 1,
                        "SubscriptionIntervalNo": 0,
                        "BillingIntervalNo": 0
                    }
                ],
                "Version": 1,
                "VersionActiveDate": "2026-04-23T15:57:14.106747"
            }
        ],
        "LastIntervalNo": 0,
        "LastBillingIntervalNo": 0,
        "NextBillingCurrencyId": "USD",
        "NextBillingCustomerGrossPrice": 800.0,
        "NextBillingCustomerNetPrice": 672.27,
        "NextBillingCustomerVatPrice": 127.73,
        "NextRenewalCustomerGrossPrice": 800.0,
        "NextRenewalCustomerNetPrice": 672.27,
        "NextRenewalCustomerVatPrice": 127.73,
        "NextBillingDate": "2026-05-23T15:57:14.106747",
        "NextRenewalDate": "2026-05-23T15:57:14.106747",
        "NextBillingDateReminder": "2026-05-21T15:57:14.106747Z",
        "PaymentInfo": {
            "CardExpirationDate": {
                "Month": 12,
                "Year": 2027
            },
            "CardLastFourDigits": "765T",
            "Currency": null,
            "CurrencyId": null,
            "IsPurchaseOrder": null,
            "PaymentType": "Visa",
            "PaymentTypeId": "CCA_VIS"
        },
        "RenewalType": "Automatic",
        "StartDate": "2026-04-23T15:57:14.106747",
        "StartIntervalDayCount": 0,
        "StartIntervalMonthCount": 1,
        "Subscriptionstatus": 1,
        "ManagementModel": "One",
        "SelfServiceUrl": "https://www.cleverbridge.com/864/s/s68574751-jsIbr45NbQcuZ2PO"
    },
    "ResultMessage": "OK"
}

Step 2: Preview of pro-rated billing amount

If the API call is formatted as described below, it will:

Calculate the pro-rated price to be billed if the 15 additional users are added.
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
Not change any data in the Cleverbridge system.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	AlignToCurrentInterval: true GetCustomerPricePreviewOnly: true	The subscription is changed as requested in the API call.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	15	Total number of items after the update.
SubscriptionId	str	Yes	S68574751	The unique identifier of the subscription.

JSON body

{
    "Quantity": 15,
    "RunningNumber": 1,
    "SubscriptionId": "S68574751",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": true
    }
}

Request

curl --location 'https://rest.cleverbridge.com/subscription/increasesubscriptionitemquantity' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' 
--data '{
    "Quantity": 15,
    "RunningNumber": 1,
    "SubscriptionId": "S68574751",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": true
    }
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "Quantity": 15,
  "RunningNumber": 1,
  "SubscriptionId": "S68574751",
  "AlignmentSettings": {
    "AlignToCurrentInterval": True,
    "GetCustomerPricePreviewOnly": True
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic ',
}
conn.request("POST", "/subscription/increasesubscriptionitemquantity", 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/increasesubscriptionitemquantity',
  '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({
  "Quantity": 15,
  "RunningNumber": 1,
  "SubscriptionId": "S68574751",
  "AlignmentSettings": {
    "AlignToCurrentInterval": true,
    "GetCustomerPricePreviewOnly": true
  }
});

req.write(postData);

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/increasesubscriptionitemquantity")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"Quantity\": 15,\n    \"RunningNumber\": 1,\n    \"SubscriptionId\": \"S68574751\",\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": true,\n        \"GetCustomerPricePreviewOnly\": true\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 1159.89,
    "AlignmentCustomerNetPrice": 974.70,
    "AlignmentCustomerVatPrice": 185.19,
    "NextBillingCustomerGrossPrice": 2000.0,
    "NextBillingCustomerNetPrice": 1680.67,
    "NextBillingCustomerVatPrice": 319.33,
    "NextRenewalCustomerGrossPrice": 2000.0,
    "NextRenewalCustomerNetPrice": 1680.67,
    "NextRenewalCustomerVatPrice": 319.33,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Step 3: Increase quantity

If the API call is formatted as described below, it will update the customer's subscription data in the Cleverbridge platform.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	AlignToCurrentInterval: true GetCustomerPricePreviewOnly: false	The subscription is changed as requested in the API call.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	15	Total number of items after the update.
SubscriptionId	str	Yes	S68574751	The unique identifier of the subscription.

Request

curl --location 'https://rest.cleverbridge.com/subscription/increasesubscriptionitemquantity' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' 
--data '{
    "Quantity": 15,
    "RunningNumber": 1,
    "SubscriptionId": "S68574751",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false
    }
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "Quantity": 15,
  "RunningNumber": 1,
  "SubscriptionId": "S68574751",
  "AlignmentSettings": {
    "AlignToCurrentInterval": True,
    "GetCustomerPricePreviewOnly": False
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/increasesubscriptionitemquantity", 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/increasesubscriptionitemquantity',
  '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({
  "Quantity": 15,
  "RunningNumber": 1,
  "SubscriptionId": "S68574751",
  "AlignmentSettings": {
    "AlignToCurrentInterval": true,
    "GetCustomerPricePreviewOnly": false
  }
});

req.write(postData);

req.end();

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

Response

{
    "AlignmentCustomerGrossPrice": 1039.94,
    "AlignmentCustomerNetPrice": 873.90,
    "AlignmentCustomerVatPrice": 166.04,
    "NextBillingCustomerGrossPrice": 2000.0,
    "NextBillingCustomerNetPrice": 1680.67,
    "NextBillingCustomerVatPrice": 319.33,
    "NextRenewalCustomerGrossPrice": 2000.0,
    "NextRenewalCustomerNetPrice": 1680.67,
    "NextRenewalCustomerVatPrice": 319.33,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

flowchart LR
  classDef mainColor fill:#ffffff,color:#555555,stroke:#96C34B,stroke-width:2px;

  A(["&nbsp;&nbsp;<br/><b>Price Preview</b><br/><i>Increase Subscription User Quantity</i> used to calculate preview&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Increase quantity</b><br/><i>Increase Subscription User Quantity</i> used to calculate&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Result</b><br/>15 users added, total number of users is 25&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor