Overview

This guide shows you how to implement the Update Subscription Item API endpoint to align subscription seats to the same renewal date by extending the billing interval of the original seat.

Use case

A customer purchased a Cloudify Storage subscription with 1 seat on April 30, 2026. The subscription renews monthly for $100.00, with the next renewal date on May 30, 2026.
Cloudify offers the customer an additional seat for $80.00 per month if the customer immediately extends the subscription term by six months.
On the Customer Self-Service page, the application calls the Get Subscription API endpoint to retrieve the next billing date.
After reviewing the offer, the customer clicks Buy Now.
The application calls the Update Subscription Item API endpoint to apply the update.

Result

The customer now has two active seats that renew together on November 30, 2026.

Implement the API endpoints

Call the Update Subscription Item API endpoint twice, in the first step to create a preview of the price breakdown, in the second call to extend the billing interval of the original seat and add a second seat.

Before you start

Make sure that:

The subscription has the status Active.
The discounted promotional price must already be configured in the Cleverbridge platform.
When replacing one subscription item with another, the original and the replacement items must have the same currency and billing interval.
Any changes made, including the price and/or quantity, apply to current and all future billing events unless modified subsequently.
If you add a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

For more information on which API endpoint to use, see Guidelines for When to Use UpdateSubscriptionItem vs. UpdateSubscriptionItemPrice.

🚧
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 price and next billing date

Return the next billing date in the NextBillingDate parameter of the API response so that it can be provided to the customer.

Parameters

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

Request

curl --location 'https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S68952510' 
--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=S68952510", 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=S68952510',
  '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=S68952510")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .asString();

Response

{
    "Subscription": {
        "CustomerCurrencyId": "USD",
        "CustomerId": 159769157,
        "CustomerReferenceId": "PsIKAYRk8DIdUdG1zQbyMVWtSno2LMaPtK5zwfrx",
        "CustomerReferenceNo": "",
        "EndDate": null,
        "GracePeriodDays": 0,
        "Id": 68952510,
        "IntervalDayCount": 0,
        "IntervalMonthCount": 1,
        "BillingIntervalDayCount": 0,
        "BillingIntervalMonthCount": 0,
        "Items": [
            {
                "Couponcode": "",
                "DeactivationDate": null,
                "EndDate": null,
                "IsCurrent": true,
                "LastIntervalNo": 0,
                "NextBillingCurrencyId": "USD",
                "NextBillingCustomerGrossPrice": 100.0,
                "NextBillingCustomerNetPrice": 84.03,
                "NextBillingCustomerVatPrice": 15.97,
                "NextRenewalCustomerGrossPrice": 100.0,
                "NextRenewalCustomerNetPrice": 84.03,
                "NextRenewalCustomerVatPrice": 15.97,
                "ProductId": 293103,
                "ProductName": "Cloudify Storage Monthly Renewal",
                "ProductNameExtension": "Cloud Storage",
                "PromotionId": null,
                "Quantity": 1,
                "RecurrenceCount": null,
                "RunningNo": 1,
                "StartDate": "2026-05-21T12:53:44.776988",
                "Status": 1,
                "SubscriptionId": 68952510,
                "SubscriptionPurchaseItems": [
                    {
                        "PurchaseId": 541791750,
                        "PurchaseItemRunningNo": 1,
                        "SubscriptionIntervalNo": 0,
                        "BillingIntervalNo": 0
                    }
                ],
                "Version": 1,
                "VersionActiveDate": "2026-05-21T12:53:44.776988"
            }
        ],
        "LastIntervalNo": 0,
        "LastBillingIntervalNo": 0,
        "NextBillingCurrencyId": "USD",
        "NextBillingCustomerGrossPrice": 100.0,
        "NextBillingCustomerNetPrice": 84.03,
        "NextBillingCustomerVatPrice": 15.97,
        "NextRenewalCustomerGrossPrice": 100.0,
        "NextRenewalCustomerNetPrice": 84.03,
        "NextRenewalCustomerVatPrice": 15.97,
        "NextBillingDate": "2026-06-21T12:53:44.776988",
        "NextRenewalDate": "2026-06-21T12:53:44.776988",
        "NextBillingDateReminder": "2026-06-19T12:53:44.776988Z",
        "PaymentInfo": {
            "CardExpirationDate": {
                "Month": 12,
                "Year": 2031
            },
            "CardLastFourDigits": "765T",
            "Currency": null,
            "CurrencyId": null,
            "IsPurchaseOrder": null,
            "PaymentType": "Visa",
            "PaymentTypeId": "CCA_VIS"
        },
        "RenewalType": "Automatic",
        "StartDate": "2026-05-21T12:53:44.776988",
        "StartIntervalDayCount": 0,
        "StartIntervalMonthCount": 1,
        "Subscriptionstatus": 1,
        "ManagementModel": "One",
        "SelfServiceUrl": "https://www.cleverbridge.com/864/s/s68952510-6L9DiAmqkSfRkcXQ"
    },
    "ResultMessage": "OK"
}

Step 2: Apply the subscription update

In the second call, update the customer's subscription data in the Cleverbridge platform using the Update Subscription Item API endpoint.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	AlignToCurrentInterval: true GetCustomerPricePreviewOnly: false	The subscription is changed as requested in the API call.
ProductId	int	Yes	293103	Product ID for the subscription item usage.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	2	Total number of items after the update.
SubscriptionId	str	Yes	S68952510	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/updatesubscriptionitem' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' 
--data '{
    "ProductId": 293103,
    "RunningNumber": 1,
    "SubscriptionId": "S68952510",
    "UpdateAction": 1,
    "Quantity": 2,
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false
    }
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "ProductId": 293103,
  "RunningNumber": 1,
  "SubscriptionId": "S68952510",
  "UpdateAction": 1,
  "Quantity": 2,
  "AlignmentSettings": {
    "AlignToCurrentInterval": 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({
  "ProductId": 293103,
  "RunningNumber": 1,
  "SubscriptionId": "S68952510",
  "UpdateAction": 1,
  "Quantity": 2,
  "AlignmentSettings": {
    "AlignToCurrentInterval": 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    \"ProductId\": 293103,\n    \"RunningNumber\": 1,\n    \"SubscriptionId\": \"S68952510\",\n    \"UpdateAction\": 1,\n    \"Quantity\": 2,\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": true,\n        \"GetCustomerPricePreviewOnly\": false\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 1575.34,
    "AlignmentCustomerNetPrice": 1323.82,
    "AlignmentCustomerVatPrice": 251.52,
    "NextBillingCustomerGrossPrice": 200.0,
    "NextBillingCustomerNetPrice": 168.07,
    "NextBillingCustomerVatPrice": 31.93,
    "NextRenewalCustomerGrossPrice": 200.0,
    "NextRenewalCustomerNetPrice": 168.07,
    "NextRenewalCustomerVatPrice": 31.93,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Response 2

{
    "AlignmentCustomerGrossPrice": 58.07,
    "AlignmentCustomerNetPrice": 48.8,
    "AlignmentCustomerVatPrice": 9.27,
    "NextBillingCustomerGrossPrice": 160,
    "NextBillingCustomerNetPrice": 134.45,
    "NextBillingCustomerVatPrice": 25.55,
    "NextRenewalCustomerGrossPrice": 160,
    "NextRenewalCustomerNetPrice": 134.45,
    "NextRenewalCustomerVatPrice": 25.55,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>Promotional offer sent</b><br/>The customer receives an offer to buy additional seat <br/> at a discounted price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Customer Self-Service</b><br/><i>Update Subscription Item</i> endpoint to obtain and display the price of the additional seat&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Purchase confirmation</b><br/>The customer clicks <b>Buy Now</b>. <br/><i>Update Subscription Item</i> endpoint  used to extend the subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor