Overview

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

Use case

The customer reaches the data limit of their current Cloudify plan.
Cloudify offers the customer an upgrade with a new price and a link to review the updated subscription details.
Cloudify uses the Update Subscription Item API endpoint to immediately upgrade and renew the subscription.

Result The new billing interval starts right away, and the customer is shown a confirmation page.

Implement the Update Subscription Item API endpoint

Before you start

🚧
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.

Make sure that:

The current billing interval has started and the next billing date has not been reached yet.
The renewal is not combined with a subscription alignment.

📘
Note
Changing the billing interval with the Update Subscription Item API endpoint is only supported for single-item subscriptions.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	AlignToCurrentInterval: false GetCustomerPricePreviewOnly: false	The subscription is changed as requested in the API call. See Alignment Settings for more information.
ProductId	int	Yes	293103	ID of the new product.
ResetBillingInterval	bool	Yes	true	Set to true to immediately start the new billing interval. If set to `true`, `TriggerImmediateRenewal` must also be `true`.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	1	Total number of items after the update.
SubscriptionId	str	Yes	S67632293	The unique identifier of the subscription.
UpdateAction	str	Yes	Upgrade	Used for documentation purposes only and does not affect billing behavior. See the note below.
TriggerImmediateRenewal	bool	Yes	true	Triggers a renewal immediately. As a result, it also extends the next billing cycle by the remaining time of current cycle.

JSON body

{
    "ProductId": 293103,
    "Quantity": 1,
    "ResetBillingInterval": true,
    "RunningNumber": 1,
    "SubscriptionId": "S67632293",
    "UpdateAction": 0,
    "TriggerImmediateRenewal": true,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    }

}

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,
    "Quantity": 1,
    "ResetBillingInterval": true,
    "RunningNumber": 1,
    "SubscriptionId": "S67632293",
    "UpdateAction": 0,
    "TriggerImmediateRenewal": true,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    }

}'

import http.client
import json

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

Response

{
    "ContinueUrl": "https://www.cleverbridge.com/864/p/539443630-k7NXzfAj4rmrHmGzYh5p",
    "NextBillingDate": "2026-06-17T09:34:53.480205",
    "NextRenewalDate": "2026-06-17T09:34:53.480205",
    "TransactionStatus": "Success",
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 60.0,
    "NextBillingCustomerNetPrice": 50.42,
    "NextBillingCustomerVatPrice": 9.58,
    "NextRenewalCustomerGrossPrice": 60.0,
    "NextRenewalCustomerNetPrice": 50.42,
    "NextRenewalCustomerVatPrice": 9.58,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>Data limit reached</b><br/>The customer wants to cancel their subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Upgrade offer presented</b><br/>Cloudify offers a new price with a link to review the updated subscription details&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Upgrade & renewal</b><br/>Cloudify uses the <i>Update Subscription Item</i> API to immediately upgrade and renew the subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor