Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus
Start typing to search…

Add users to a subscription

Overview

This guide shows you how to implement the Increase Subscription Item Quantity endpoint to change the quantity of subscription users.

Use Case

The customer wants to increase the number of seats from 10 users to 15 users.

  1. August 15th: customer is billed $50 for the monthly subscription: $50.00 for 10 seats priced at $5.00 per user.
  2. September 4th: customer increases the number of users to 15 seats, effective at the next billing date.
  3. September 15th: Cleverbridge bills $75 for the monthly interval.

Example checkout


Implement API endpoints

First call the Get Subscription to retrieve the number of users of the subscription, then call the Increase Subscription Item Quantity endpoint endpoint.

Before you start

Make sure that:

  • The subscription has the status Active.
  • Any changes made, including the price and/or quantity, apply to all future billing events unless modified subsequently.
🚧

Important

Get the customer's consent for changes to subscriptions. 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 (first call)

Use the given parameters to retrieve the quantity of the subscription users.

Parameters

ParameterTypeRequiredExampleNotes
RunningNumberintYes1Matches the running number of the subscription item for which the quantity is needed.
IsCurrentboolYestrueTotal number of items after the update.
SubscriptionIdstrYesS67661151The unique identifier of the subscription.

First call: Get Subscription API endpoint

From the Items array, retrieve the Quantity value (e.g., Quantity: 10) from the relevant item object.

curl --request GET \
  "https://rest.cleverbridge.com/subscription/getsubscription?SubscriptionId=284947&RunningNumber=1&IsCurrent=true" \
  --header "Accept: application/json" \
  --header "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS"
import requests

url = "https://rest.cleverbridge.com/subscription/getsubscription"

params = {
    "SubscriptionId": "S67661151",
    "RunningNumber": 1,
    "IsCurrent": "true"
}

headers = {
    "Accept": "application/json",
    "Authorization": "Basic YOUR_BASE64_ENCODED_CREDENTIALS"
}

response = requests.get(url, headers=headers, params=params)

print("Status:", response.status_code)
print("Response:", response.text)
const axios = require("axios");

const url = "https://rest.cleverbridge.com/subscription/getsubscription";

axios.get(url, {
  headers: {
    "Accept": "application/json",
    "Authorization": "Basic YOUR_BASE64_ENCODED_CREDENTIALS"
  },
  params: {
    SubscriptionId: "284947",
    RunningNumber: 1,
    IsCurrent: true
  }
})
.then(response => {
  console.log("Status:", response.status);
  console.log("Data:", response.data);
})
.catch(err => {
  console.error(err.response?.data || err.message);
});

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class GetSubscriptionSample {
    public static void main(String[] args) {
        try {
            String query =
                "SubscriptionId=284947&RunningNumber=1&IsCurrent=true";

            URL url = new URL(
                "https://rest.cleverbridge.com/subscription/getsubscription?" + query
            );

            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty(
                "Authorization",
                "Basic YOUR_BASE64_ENCODED_CREDENTIALS"
            );

            int status = conn.getResponseCode();
            System.out.println("Status: " + status);

            BufferedReader reader = new BufferedReader(
                new InputStreamReader(
                    status >= 200 && status < 300 ?
                        conn.getInputStream() : conn.getErrorStream(),
                    "utf-8"
                )
            );

            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) sb.append(line);
            reader.close();

            System.out.println("Response:");
            System.out.println(sb.toString());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Response


{
	"Subscription":{
		"CustomerCurrencyId":"USD",
		"CustomerId":157824676,
		"CustomerReferenceId":"uEd5Jq3yOMs1NkEh8bV7nu9zJZJAUe2vyYxnVgL8",
		"CustomerReferenceNo":"",
		"EndDate":null,
		"GracePeriodDays":0,
		"Id":67661151,
		"IntervalDayCount":0,
		"IntervalMonthCount":1,
		"BillingIntervalDayCount":0,
		"BillingIntervalMonthCount":0,
		"Items":[
			{
				"Couponcode":"",
				"DeactivationDate":null,
				"EndDate":null,
				"IsCurrent":true,
				"LastIntervalNo":0,
				"NextBillingCurrencyId":"USD",
				"NextBillingCustomerGrossPrice":50.0,
				"PromotionId":null,
				"Quantity":10,
				"RecurrenceCount":null,
				"RunningNo":1,
				"StartDate":"2026-02-18T16:59:11.003593",
				"Status":1,
				"SubscriptionId":67661151,
				"SubscriptionPurchaseItems":[
					{
						"PurchaseId":532209743,
						"PurchaseItemRunningNo":1,
						"SubscriptionIntervalNo":0,
						"BillingIntervalNo":0
					}
				],
				"Version":1,
				"VersionActiveDate":"2026-02-18T16:59:11.003593"
			}
		],
		"LastIntervalNo":0,
		"LastBillingIntervalNo":0,
		"NextBillingCurrencyId":"USD",
		"NextBillingCustomerGrossPrice":50.0,
		"NextBillingCustomerNetPrice":42.02,
		"NextBillingCustomerVatPrice":7.98,
		"NextRenewalCustomerGrossPrice":50.0,
		"NextRenewalCustomerNetPrice":42.02,
		"NextRenewalCustomerVatPrice":7.98,
		"NextBillingDate":"2026-03-18T16:59:11.003593",
		"NextRenewalDate":"2026-03-18T16:59:11.003593",
		"NextBillingDateReminder":"2026-03-16T16:59:11.003593Z",
		"PaymentInfo":{
			"CardExpirationDate":{
				"Month":12,
				"Year":2027
			},
			"CardLastFourDigits":"765T",
			"Currency":null,
			"CurrencyId":null,
			"IsPurchaseOrder":null,
			"PaymentType":"Visa",
			"PaymentTypeId":"CCA_VIS"
		},
		"RenewalType":"Automatic",
		"StartDate":"2026-02-18T16:59:11.003593",
		"StartIntervalDayCount":0,
		"StartIntervalMonthCount":1,
		"Subscriptionstatus":1,
		"ManagementModel":"One",
		"SelfServiceUrl":"https://www.cleverbridge.com/864/s/s67661151-yRpzOYTr1cDep5hX"
	},
	"ResultMessage":"OK"
}

Step 2: Call Increase Subscription Item Quantity endpoint

Parameters

Parameter

Type

Required

Example

Notes

AlignmentSettings

obj

No

AlignToCurrentInterval: false

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

S67661151

The unique identifier of the subscription.

UpdateAction

str

No

upgrade

The value set does not affect transaction processing.
See the note below


📘

Note

The UpdateAction parameter is currently used for documentation and tracking only. The value set does not affect transaction processing.

The supported values are as follows:

  • For upgrades, set the parameter to upgrade(or 1 for JSON)
  • For downgrades, set the parameter to downgrade, (or 2 for JSON)
  • For all other changes, set the parameter to update (or 0 for JSON)

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": "S67661151",
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": true,
    "ExtendInterval": true
  }
import requests
import json

url = "https://rest.cleverbridge.com/subscription/increasesubscriptionitemquantity"

payload = json.dumps({
  "Quantity": 15,
  "RunningNumber": 1,
  "SubscriptionId": "S67661151",
  "AlignmentSettings": {
    "AlignToCurrentInterval": False,
    "GetCustomerPricePreviewOnly": True,
    "ExtendInterval": True
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

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',
    'Cookie': '__cf_bm=pR0muHiI7aJpP6CQYkXygL1F1HNsirSdvQz9jIHhCec-1772547176.414088-1.0.1.1-tyczeNXrbLraEJdkWG.pNqeinqYyhFOmTGP6EzU77f6_m2AfKa8DFCbofoSwTKq7DCC_3CSc1oJzxxDj6or8V3FOzctw6cofCwK2yN2VZ0Sf0hLOZF2XUQe0iristGHl; __cflb=02DiuGUwaHeX5xCq1y63p8duqPwzkwbxcw4twjvtnziiY'
  },
  '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": "S67661151",
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": true,
    "ExtendInterval": 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", "YOUR_BASE64_ENCODED_CREDENTIALS
")
  .body("{\n  \"Quantity\": 15,\n  \"RunningNumber\": 1,\n  \"SubscriptionId\": \"S67661151\",\n  \"AlignmentSettings\": {\n    \"AlignToCurrentInterval\": false,\n    \"GetCustomerPricePreviewOnly\": true,\n    \"ExtendInterval\": true\n  }\n}")
  .asString();

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>August 15th</b><br/>Subscription renewed for €100<br/>(€50 base + 10 users × €5 per user per month)&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>The customer adds 5 new users,<br/>effective at the next billing date&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>September 15</b><br/>The customer is billed €125:<br/>€50 for base usage<br/>€75 for 15 users <br/>(15 × €5)&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor

Updated 1 day ago