Overview

This guide shows you how to implement the Update Subscription Item endpoint to upgrade and renew the customer's subscription immediately.

Use case

Allow a customer to upgrade from monthly to yearly and renew a subscription effective immediately.

A Cloudify Storage customer pays $100.00 monthly fee, decides to switch to the annual payment of $900.00, saving $300 per year.
The page uses the Get Subscription endpoint to obtain and display the current price of the subscription and the next billing date.
After reviewing this information, the customer confirms this purchase by clicking a Buy Now button on the page. The page uses the Update Subscription Item endpoint to upgrade and renew the customer's cloud storage subscription immediately.

Result

The customer upgrades from monthly to yearly billing, is charged immediately for the annual subscription, and begins a new yearly billing interval right away.

Implement the Update Subscription Item endpoint

Before you start

Make sure that:

The subscription has the status Active.
The current billing interval has started.
The renewal is not combined with an alignment of the subscription.
The product billed yearly has been set up in the Cleverbridge platform.

Additional considerations

When you add a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

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

In the first call, retrieve the price and the next billing date to display current pricing and renewal dates to the customer before confirmation..

Parameters

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

Request

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

import http.client

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

Response

{
    "Subscription": {
        "CustomerCurrencyId": "USD",
        "CustomerId": 159513108,
        "CustomerReferenceId": "uzaKjIEAzAb8aY1Fn67xJhtw1xIaybIRqoWvYjKP",
        "CustomerReferenceNo": "",
        "EndDate": null,
        "GracePeriodDays": 0,
        "Id": 68774933,
        "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-08T10:43:16.675494",
                "Status": 1,
                "SubscriptionId": 68774933,
                "SubscriptionPurchaseItems": [
                    {
                        "PurchaseId": 540485113,
                        "PurchaseItemRunningNo": 1,
                        "SubscriptionIntervalNo": 0,
                        "BillingIntervalNo": 0
                    }
                ],
                "Version": 1,
                "VersionActiveDate": "2026-05-08T10:43:16.675494"
            }
        ],
        "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-08T10:43:16.675494",
        "NextRenewalDate": "2026-06-08T10:43:16.675494",
        "NextBillingDateReminder": "2026-06-06T10:43:16.675494Z",
        "PaymentInfo": {
            "CardExpirationDate": {
                "Month": 11,
                "Year": 2027
            },
            "CardLastFourDigits": "765T",
            "Currency": null,
            "CurrencyId": null,
            "IsPurchaseOrder": null,
            "PaymentType": "Visa",
            "PaymentTypeId": "CCA_VIS"
        },
        "RenewalType": "Automatic",
        "StartDate": "2026-05-08T10:43:16.675494",
        "StartIntervalDayCount": 0,
        "StartIntervalMonthCount": 1,
        "Subscriptionstatus": 1,
        "ManagementModel": "One",
        "SelfServiceUrl": "https://www.cleverbridge.com/864/s/s68774933-m32u0kvMsmBjN83G"
    },
    "ResultMessage": "OK"
}

Step 2: Upgrade and renew the subscription immediately

Upgrade by replacing the monthly plan with the yearly plan and renew the subscription for another billing interval.

Parameters

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

Parameter	Type	Required	Example	Notes
ProductId	int	Yes	293104	The product ID for the annual plan product (not the current monthly plan product being replaced).
RunningNumber	int	Yes	1	Running number of the item in the subscription. Use the `RunningNo` value returned from Get Subscription response.
Quantity	int	Yes	1	Total number of items after the update.
SubscriptionId	str	Yes	S68774933	The unique identifier of the subscription.
UpdateAction	str	No	0	The value set does not affect transaction processing. See the note below.
TriggerImmediateRenewal	bool	Yes	true	Triggers a renewal immediately. As a result, it also extends the next billing cycle by remaining time of current cycle. You should use this with caution because it is not a standard action for subscription upgrades.
ResetBillingInterval	bool	Yes	true	Set to true to immediately start the new billing interval. If you use this option, you must also set `TriggerImmediateRenewal` to `true`.

📘
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 BASE64_ENCODED_USERNAME_PASSWORD' 
--data '{
    "ProductId": 293104,
    "RunningNumber": 1,
    "Quantity": 1,
    "SubscriptionId": "S68774933",
    "UpdateAction": 0,
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval": true
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
    "ProductId": 293104,
    "RunningNumber": 1,
    "Quantity": 1,
    "SubscriptionId": "S68774933",
    "UpdateAction": 0,
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval": true
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic BASE64_ENCODED_USERNAME_PASSWORD',
}
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 BASE64_ENCODED_USERNAME_PASSWORD',
  },
  '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": 293104,
    "RunningNumber": 1,
    "Quantity": 1,
    "SubscriptionId": "S68774933",
    "UpdateAction": 0,
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval": 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 BASE64_ENCODED_USERNAME_PASSWORD")
  .body("{\n    \"ProductId\": 293104,\n    \"RunningNumber\": 1,\n    \"Quantity\": 1,\n    \"SubscriptionId\": \"S68774933\",\n    \"UpdateAction\": 0,\n    \"TriggerImmediateRenewal\": true,\n    \"ResetBillingInterval\": true\n}")
  .asString();

Response

{
    "ContinueUrl": "https://www.cleverbridge.com/864/p/540486524-LEw3mWFlGSsOkIaBCyis",
    "NextBillingDate": "2027-05-08T10:35:52.430601",
    "NextRenewalDate": "2027-05-08T10:35:52.430601",
    "TransactionStatus": "Success",
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 900.0,
    "NextBillingCustomerNetPrice": 756.3,
    "NextBillingCustomerVatPrice": 143.7,
    "NextRenewalCustomerGrossPrice": 900.0,
    "NextRenewalCustomerNetPrice": 756.3,
    "NextRenewalCustomerVatPrice": 143.7,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>Upgrade</b><br/>Cloudify customer decides to switch from monthly to yearly subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Confirmation</b><br/>The customer confirms they want to proceed with the upgrade&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Billing</b><br/>Cleverbridge bills the customer immediately&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor