Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus

Increase Subscription User Quantity Immediately

Overview

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

Use case

  1. A Cloudify customer currently has 10 subscription users and wants to add 15 more users during the current billing period.
  2. The customer chooses to increase the user quantity.
  3. Increase Subscription Item Quantity endpoint is used to calculate the pro-rated price for the 15 additional users.
  4. After reviewing the pricing information, the customer confirms the update. Increase Subscription Item Quantity endpoint is called again to apply the update.
  5. The Cleverbridge platform automatically bills the customer the pro-rated amount.

Result

15 users were added immediately, bringing the total number of users to 25. The customer was charged the pro-rated alignment amount and future renewals are based on the new quantity.

Implement the API endpoint

Before you start

Make sure that:

  • The customer has a subscription with an Active status.
  • You obtain the customer's consent before making changes to the subscription.
🚧

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 current quantity

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

ParameterTypeRequiredExampleNotes
SubscriptionIdstrYesS67661151The 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": {
    "Id": 68574751,
    "CustomerId": 159215775,
    "CustomerCurrencyId": "USD",
    "CustomerReferenceId": "skTI6EGSpGU1kODfm86bGsERjB5DGORw8Xj8wTGA",

    "Status": {
      "SubscriptionStatus": 1,
      "RenewalType": "Automatic",
      "ManagementModel": "One",
      "GracePeriodDays": 0
    },

    "Billing": {
      "IntervalMonthCount": 1,
      "IntervalDayCount": 0,
      "BillingIntervalMonthCount": 0,
      "BillingIntervalDayCount": 0,

      "NextBillingDate": "2026-05-23T15:57:14.106747",
      "NextRenewalDate": "2026-05-23T15:57:14.106747",
      "NextBillingDateReminder": "2026-05-21T15:57:14.106747Z",

      "NextBillingCustomerGrossPrice": 800.00,
      "NextBillingCustomerNetPrice": 672.27,
      "NextBillingCustomerVatPrice": 127.73,

      "NextRenewalCustomerGrossPrice": 800.00,
      "NextRenewalCustomerNetPrice": 672.27,
      "NextRenewalCustomerVatPrice": 127.73
    },

    "Items": [
      {
        "RunningNo": 1,
        "ProductId": 293160,
        "ProductName": "Cloudify M",

        "Quantity": 10,
        "Status": 1,
        "IsCurrent": true,

        "StartDate": "2026-04-23T15:57:14.106747",
        "EndDate": null,
        "DeactivationDate": null,

        "Pricing": {
          "CurrencyId": "USD",

          "NextBillingCustomerGrossPrice": 800.00,
          "NextBillingCustomerNetPrice": 672.27,
          "NextBillingCustomerVatPrice": 127.73,

          "NextRenewalCustomerGrossPrice": 800.00,
          "NextRenewalCustomerNetPrice": 672.27,
          "NextRenewalCustomerVatPrice": 127.73
        },

        "SubscriptionPurchaseItems": [
          {
            "PurchaseId": 538988784,
            "PurchaseItemRunningNo": 1,
            "SubscriptionIntervalNo": 0,
            "BillingIntervalNo": 0
          }
        ]
      }
    ],

    "PaymentInfo": {
      "PaymentType": "Visa",
      "PaymentTypeId": "CCA_VIS",
      "CardLastFourDigits": "765T",
      "CardExpirationDate": {
        "Month": 12,
        "Year": 2027
      }
    },

    "SelfServiceUrl": "https://www.cleverbridge.com/864/s/s68574751-jsIbr45NbQcuZ2PO"
  },

  "ResultMessage": "OK"
}

Step 2: Preview the pro-rated charge

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 charge in the AlignmentCustomerGrossPrice field so that it can be displayed to the customer before the change is applied.
  • Not change any data in the Cleverbridge system.

Parameters

Parameter

Type

Required

Example

Notes

AlignmentSettings

obj

No

AlignToCurrentInterval: true

GetCustomerPricePreviewOnly: true

The subscription is NOT changed as requested in the API call. The API only returns a pricing preview.

RunningNumber

int

Yes

1

Running number of the item in the subscription.
Corresponds to RunningNo returned in the Get Subscription response.

Quantity

int

Yes

15

Additional number of items / licenses to be added to the subscription.

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": 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"
}

The response shows the immediate alignment charge that would be billed for the 15 additional users (AlignmentCustomerGrossPrice) and the new renewal price that will apply on future billing dates (NextRenewalCustomerGrossPrice). Because GetCustomerPricePreviewOnly is set to true, no subscription data is changed.

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. Use the RunningNo value returned by the Get Subscription response.

Quantity

int

Yes

15

The number of additional users.

SubscriptionId

str

Yes

S68574751

The unique identifier of the subscription.

📘

Note

The Quantity parameter specifies the number of users to add, not the new total quantity.
In this example, 15 users are added to the existing quantity of 10, resulting in a total of 25 users.

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 apply the update&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Result</b><br/>15 users were added, bringing the total number of users to 25&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor