Overview

This guide shows you how to implement the Update Subscription Item Price endpoint to change the price effective immediately.

Use case

A Cloudify customer pays $100.00 monthly for cloud storage.
Due to rising electricity costs, Cloudify increases the price to $120.00 per month.
After obtaining the customer's consent, the Cloudify intranet page calls the Update Subscription Item Price endpoint to apply the new price immediately.

Result

The updated price is applied immediately. A prorated alignment charge is generated for the current billing interval.

Implement the Update Subscription Item Price endpoint

When to use the Update Subscription Item Price endpoint

Use the UpdateSubscriptionItemPrice endpoint for new implementations when only the price (and optionally quantity) needs to be updated.

Use UpdateSubscriptionItem when additional subscription properties must be modified alongside the price or quantity.

📘
Note
If you only need to change the price and/or quantity of a subscription item, both endpoints can be used.

Before you start

Make sure that:

The customer has a subscription with an Active status.
The current billing interval has started and the next billing date has not yet been reached.
Any changes made, including the price and/or quantity, apply to the current and all future billing events unless modified subsequently.

🚧
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: Get Subscription

Parameters

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

Request

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

Response

{
  "Subscription": {
    "Id": 67439867,
    "NextBillingDate": "2026-07-16T13:06:58",
    "Items": [
      {
        "RunningNo": 1,
        "ProductName": "Cloudify Gold",
        "Quantity": 1,
        "Status": 1,
        "NextRenewalCustomerGrossPrice": 100.00,
        "IsCurrent": true
      }
    ]
  },
  "ResultMessage": "OK"
}

Step 2: Update Subscription Item Price

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	`AlignToCurrentInterval: true` `GetCustomerPricePreviewOnly: false`	The subscription is changed as requested in the API call.
CustomerPrice	obj	Yes	`CurrencyId: USD` `IsGross: true` `Value: 120.00`	The pricing information presented to the customer during the purchase process.
RunningNumber	int	Yes	1	Running number of the item in the subscription. Corresponds to `RunningNo` returned in the Get Subscription response.
SubscriptionId	str	Yes	S67439867	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/updatesubscriptionitemprice' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' 
--data '{
    "SubscriptionId": "S67439867",
    "RunningNumber": 1,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 120.00
    }
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
    "SubscriptionId": "S67439867",
    "RunningNumber": 1,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 120.00
    }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
}
conn.request("POST", "/subscription/updatesubscriptionitemprice", 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/updatesubscriptionitemprice',
  '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({
    "SubscriptionId": "S67439867",
    "RunningNumber": 1,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 120.00
    }
});

req.write(postData);

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/updatesubscriptionitemprice")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"SubscriptionId\": \"S67439867\",\n    \"RunningNumber\": 1,\n    \"UpdateAction\": \"upgrade\",\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": true,\n        \"GetCustomerPricePreviewOnly\": false\n    },\n    \"CustomerPrice\": {\n        \"CurrencyId\": \"USD\",\n        \"IsGross\": true,\n        \"Value\": 120.00\n    }\n}")
  .asString();

JSON body

{
    "SubscriptionId": "S67439867",
    "RunningNumber": 1,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 120.00
    }
}

Response

{
    "AlignmentCustomerGrossPrice": 10.67,
    "AlignmentCustomerNetPrice": 8.97,
    "AlignmentCustomerVatPrice": 1.70,
    "NextBillingCustomerGrossPrice": 120.00,
    "NextBillingCustomerNetPrice": 100.84,
    "NextBillingCustomerVatPrice": 19.16,
    "NextRenewalCustomerGrossPrice": 120.00,
    "NextRenewalCustomerNetPrice": 100.84,
    "NextRenewalCustomerVatPrice": 19.16,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>Price increase</b><br/>Price per subscription goes up&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Customer agrees</b><br/>The customer accepts the new price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Billing</b><br/>Cleverbridge charges the prorated price difference immediately.&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor