Overview

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

Use case

The customer reaches the data limit on their current Cloudify plan and considers canceling.
Cloudify offers an early renewal at a lower price due to the downgrade, and the customer accepts after reviewing the updated subscription details.
Cloudify uses the Update Subscription Item API endpoint to downgrade and renew the subscription immediately.

Result
The new billing interval starts right away, and the customer regains access on the downgraded plan.

Implement 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.
Any changes made, including the price and/or quantity, apply to all future billing events unless modified subsequently.
The renewal is not combined with an alignment of the subscription.
Use of the AlignmentSettings parameter in the API request is required.
Before doing so, see Get Started with Subscriptions > Alignment Settings.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	`{ "AlignToCurrentInterval": false, "GetCustomerPricePreviewOnly": false }`	The subscription is changed as requested in the API call.
CustomerPrice	obj	Yes	`{ "CurrencyId": "USD", "IsGross": true, "Value": 60.00 }`	Pricing information that the customer receives during the purchase process.
ProductId	int	Yes	293103	Product ID for the subscription item usage.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
ResetBillingInterval	bool	Yes	true	Set to true to immediately start the new billing interval.
Quantity	int	Yes	1	Total number of items after the update.
SubscriptionId	str	Yes	S67632293	The unique identifier of the subscription.
UpdateAction	str	No	Downgrade	The value set does not affect transaction processing. See the note below.
TriggerImmediateRenewal	bool	Yes	true	Triggers a renewal immediately. A new billing interval starts immediately when used with `ResetBillingInterval = 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)

JSON body

{
    "ProductId": 293103,
    "Quantity": 1,
    "RunningNumber": 1,
    "ResetBillingInterval": true,
    "SubscriptionId": "S67632293",
    "UpdateAction": "Downgrade",
    "TriggerImmediateRenewal": true,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 60.00
    }
}

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,
    "RunningNumber": 1,
    "ResetBillingInterval": true,
    "SubscriptionId": "S67632293",
    "UpdateAction": "Downgrade",
    "TriggerImmediateRenewal": true,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 60.00
    }
}'

import http.client
import json

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

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    \"RunningNumber\": 1,\n    \"ResetBillingInterval\": true,\n    \"SubscriptionId\": \"S67632293\",\n    \"UpdateAction\": \"Downgrade\",\n    \"TriggerImmediateRenewal\": true,\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": false,\n        \"GetCustomerPricePreviewOnly\": false\n    },\n    \"CustomerPrice\": {\n        \"CurrencyId\": \"USD\",\n        \"IsGross\": true,\n        \"Value\": 60.00\n    }\n}")
  .asString();

Response

{
    "ContinueUrl": "https://www.cleverbridge.com/864/p/538336097-fDloHtUBF05XlmOK2eOH",
    "NextBillingDate": "2026-05-17T09:34:53.480205",
    "NextRenewalDate": "2026-05-17T09:34:53.480205",
    "TransactionStatus": "Success",
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 60.00,
    "NextBillingCustomerNetPrice": 50.42,
    "NextBillingCustomerVatPrice": 9.58,
    "NextRenewalCustomerGrossPrice": 60.00,
    "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 uses up the 20 GB data limit&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Cancellation</b><br/>The customer decides to cancel their subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Deactivation</b><br/><i>Update Subscription Renewal Type</i> API endpoint used to turn off automatic renewal&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor