Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus

Make Quantity and Quantity-Based Price Changes Immediately

Overview

This guide shows you how to implement the Update Subscription Item Price endpoint to apply the volume-based price effective immediately.

Use case

Discount offer for additional user accounts.

  1. A Cloudify customer currently has 10 user accounts and pays $100.00 per month ($10.00 per user account).

  2. The customer receives an offer to purchase additional user accounts at a discounted rate.
    Any user accounts beyond the initial 10 qualify for a 20% discount, reducing the monthly price per additional account from $10.00 to $8.00.

    Offer Details:

    User AccountsMonthly price per user account
    1-10$10.00
    11 or more$8.00

  3. The customer accepts the offer and purchases 5 additional user accounts. The quantity and price update are applied to the subscription and become effective with the next billing interval.

Result

Starting with the next billing interval, the customer has 15 user accounts:

  • The first 10 user accounts continue at $10.00 per account per month.
  • The additional 5 user accounts are billed at the discounted rate of $8.00 per account per month.

The customer’s new monthly total is $140.00.

.

📘

Note

Cases in which the resulting pro-rated billing calculation results in a negative amount are not supported.

Implement the Update Subscription Item Price endpoint

Before you start

Make sure that:

  • The subscription has the status Active.
  • You have Set up Volume Pricing for the Product.
  • You have received the customer’s consent to update the subscription quantity and price.
🚧

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 the current subscription quantity

Parameters

ParameterTypeRequiredExampleNotes
SubscriptionIdstrYesS68912106The unique identifier of the subscription.

Request

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

Response

{
    "Subscription": {
        "CustomerCurrencyId": "USD",
        "CustomerId": 159711261,
        "CustomerReferenceId": "VaBOTBS9ZW3Y6lOMnf8MePEJALr8cf3l3BYiw6Up",
        "CustomerReferenceNo": "",
        "EndDate": null,
        "GracePeriodDays": 0,
        "Id": 68912106,
        "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": 292973,
                "ProductName": "Cloudify Seat",
                "ProductNameExtension": "",
                "PromotionId": null,
                "Quantity": 10,
                "RecurrenceCount": null,
                "RunningNo": 1,
                "StartDate": "2026-05-18T14:33:50.627609",
                "Status": 1,
                "SubscriptionId": 68912106,
                "SubscriptionPurchaseItems": [
                    {
                        "PurchaseId": 541478944,
                        "PurchaseItemRunningNo": 1,
                        "SubscriptionIntervalNo": 0,
                        "BillingIntervalNo": 0
                    }
                ],
                "Version": 1,
                "VersionActiveDate": "2026-05-18T14:33:50.627609"
            }
        ],
        "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-18T14:33:50.627609",
        "NextRenewalDate": "2026-06-18T14:33:50.627609",
        "NextBillingDateReminder": "2026-06-16T14:33:50.627609Z",
        "PaymentInfo": {
            "CardExpirationDate": {
                "Month": 12,
                "Year": 2027
            },
            "CardLastFourDigits": "765T",
            "Currency": null,
            "CurrencyId": null,
            "IsPurchaseOrder": null,
            "PaymentType": "Visa",
            "PaymentTypeId": "CCA_VIS"
        },
        "RenewalType": "Automatic",
        "StartDate": "2026-05-18T14:33:50.627609",
        "StartIntervalDayCount": 0,
        "StartIntervalMonthCount": 1,
        "Subscriptionstatus": 1,
        "ManagementModel": "One",
        "SelfServiceUrl": "https://www.cleverbridge.com/864/s/s68912106-JLagnz4ZIJmdPWMY"
    },
    "ResultMessage": "OK"
}


Step 2: Update the Price

Parameters

Parameter

Type

Required

Example

Notes

AlignmentSettings

obj

No

AlignToCurrentInterval: false

GetCustomerPricePreviewOnly: false

The subscription is changed as requested in the API call.

RunningNumber

int

Yes

1

Running number of the item in the subscription.

Quantity

int

Yes

15

Total number of items after the update.

SubscriptionId

str

Yes

S68912106

The unique identifier of the subscription.

UpdateAction

str

Yes

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:

  • 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

{
    "SubscriptionId": "S68912106",
    "RunningNumber": 1,
    "Quantity": 15,
    "ProductId": 292973,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    }
}

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": "S68912106",
    "RunningNumber": 1,
    "Quantity": 15,
    "ProductId": 292973,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    }
}'
 
import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S68912106",
  "RunningNumber": 1,
  "Quantity": 15,
  "ProductId": 292973,
  "UpdateAction": "upgrade",
  "AlignmentSettings": {
    "AlignToCurrentInterval": False,
    "GetCustomerPricePreviewOnly": False
  }
})
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 request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest.cleverbridge.com/subscription/updatesubscriptionitemprice',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
  },
  body: JSON.stringify({
    "SubscriptionId": "S68912106",
    "RunningNumber": 1,
    "Quantity": 15,
    "ProductId": 292973,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": false
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

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\": \"S68912106\",\n    \"RunningNumber\": 1,\n    \"Quantity\": 15,\n    \"ProductId\": 292973,\n    \"UpdateAction\": \"upgrade\",\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": false,\n        \"GetCustomerPricePreviewOnly\": false\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 140.0,
    "NextBillingCustomerNetPrice": 117.65,
    "NextBillingCustomerVatPrice": 22.35,
    "NextRenewalCustomerGrossPrice": 140.0,
    "NextRenewalCustomerNetPrice": 117.65,
    "NextRenewalCustomerVatPrice": 22.35,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram


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

  A(["&nbsp;&nbsp;<br/><b>Current Subscription</b><br/>Customer has 10 user accounts<br/>Monthly price: $100.00&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Discount Offer</b><br/>Additional seats beyond 10 get 20% discount<br/>Discounted price per additional seat: $8.00&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Offer Accepted</b><br/>Customer purchases 5 additional accounts<br/>Update effective with next billing interval&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor