Overview

This guide shows you how to implement the Get Subscription and the Update Subscription Item Price API endpoints to do change the price per seat.

Use case

The customer wants to increase the number of subscription seats from 100 to 300 and asks for a discount.
You offer to reduce the price from $5.00 to $4.00 at the time of renewal.
The Update Subscription Item Price API endpoint is used to change the price per license and the quantity of seats, effective with the next billing date.
Cleverbridge automatically bills the customer for the monthly subscription renewal.

Implement API endpoints

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 subscription has the status Active.
Any changes made, including the price and/or quantity, apply to all future billing events unless modified subsequently.

Step 1: Retrieve Subscription

In the first call, retrieve the customer’s current subscription item quantity and price by calling the Get Subscription API endpoint.

Parameters

Parameter	Type	Required	Example	Notes
SubscriptionId	str	Yes	S67890819	The unique identifier of the subscription.
isCurrent	bool	Yes	true	Whether to return only the current state.

Request

curl --location 'https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S67890819&isCurrent=true' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS'

import http.client
import mimetypes
from codecs import encode

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
boundary = ''
payload = ''
headers = {
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
  'Content-type': 'multipart/form-data; boundary={}'.format(boundary)
}
conn.request("GET", "/subscription/getsubscription?subscriptionId=S67890819&isCurrent=true", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S67890819&isCurrent=true',
  'headers': {
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
  },
  formData: {

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

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.get("https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S67890819&isCurrent=true")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .multiPartContent()
  .asString();

Response

{
    "Subscription": {
        "CustomerCurrencyId": "USD",
        "CustomerId": 158191776,
        "CustomerReferenceId": "HBHEl2qZ0ecGWyvLlQDOcPvzYBNvOzSUD0yEaF1J",
        "CustomerReferenceNo": "",
        "EndDate": null,
        "GracePeriodDays": 0,
        "Id": 67890819,
        "IntervalDayCount": 0,
        "IntervalMonthCount": 1,
        "BillingIntervalDayCount": 0,
        "BillingIntervalMonthCount": 0,
        "Items": [
            {
                "Couponcode": "",
                "DeactivationDate": null,
                "EndDate": null,
                "IsCurrent": true,
                "LastIntervalNo": 0,
                "NextBillingCurrencyId": "USD",
                "NextBillingCustomerGrossPrice": 500.0,
                "NextBillingCustomerNetPrice": 420.17,
                "NextBillingCustomerVatPrice": 79.83,
                "NextRenewalCustomerGrossPrice": 500.0,
                "NextRenewalCustomerNetPrice": 420.17,
                "NextRenewalCustomerVatPrice": 79.83,
                "ProductId": 292973,
                "ProductName": "Cloudify Seat",
                "ProductNameExtension": "",
                "PromotionId": null,
                "Quantity": 100,
                "RecurrenceCount": null,
                "RunningNo": 1,
                "StartDate": "2026-03-05T17:38:04.322598",
                "Status": 1,
                "SubscriptionId": 67890819,
                "SubscriptionPurchaseItems": [
                    {
                        "PurchaseId": 533979122,
                        "PurchaseItemRunningNo": 1,
                        "SubscriptionIntervalNo": 0,
                        "BillingIntervalNo": 0
                    }
                ],
                "Version": 1,
                "VersionActiveDate": "2026-03-05T17:38:04.322598"
            }
        ],
        "LastIntervalNo": 0,
        "LastBillingIntervalNo": 0,
        "NextBillingCurrencyId": "USD",
        "NextBillingCustomerGrossPrice": 500.0,
        "NextBillingCustomerNetPrice": 420.17,
        "NextBillingCustomerVatPrice": 79.83,
        "NextRenewalCustomerGrossPrice": 500.0,
        "NextRenewalCustomerNetPrice": 420.17,
        "NextRenewalCustomerVatPrice": 79.83,
        "NextBillingDate": "2026-04-05T17:38:04.322598",
        "NextRenewalDate": "2026-04-05T17:38:04.322598",
        "NextBillingDateReminder": "2026-04-03T17:38:04.322598Z",
        "PaymentInfo": {
            "CardExpirationDate": {
                "Month": 12,
                "Year": 2027
            },
            "CardLastFourDigits": "765T",
            "Currency": null,
            "CurrencyId": null,
            "IsPurchaseOrder": null,
            "PaymentType": "Visa",
            "PaymentTypeId": "CCA_VIS"
        },
        "RenewalType": "Automatic",
        "StartDate": "2026-03-05T17:38:04.322598",
        "StartIntervalDayCount": 0,
        "StartIntervalMonthCount": 1,
        "Subscriptionstatus": 1,
        "ManagementModel": "One",
        "SelfServiceUrl": "https://www.cleverbridge.com/864/s/s67890819-feNnFVQaqy2QcMPK"
    },
    "ResultMessage": "OK"
}

Step 2: Update Subscription Item Price and Quantity

In the second call, change the subscription in the Cleverbridge platform by calling the Update Subscription Item Price endpoint.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`	The subscription is changed as requested in the API call.
CustomerPrice	int	Yes	`CurrencyId: USD` `IsGross: true` `Value: 4.00`	Product ID for the subscription item usage.
RunningNumber	int	Yes	1	It is assumed that the seats item is the only item in the subscription.
Quantity	int	Yes	300	Total number of items after the update.
SubscriptionId	str	Yes	S67890819	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?ProductId=293039' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' 
--data '{
    "SubscriptionId": "S67890819",
    "RunningNumber": 1,
    "UpdateAction": "upgrade",
    "Quantity": 300,
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
            "CurrencyId": "USD",
            "IsGross": true,
            "Value": 4.00
    }
  }'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S67890819",
  "RunningNumber": 1,
  "UpdateAction": "upgrade",
  "Quantity": 300,
  "AlignmentSettings": {
    "AlignToCurrentInterval": False,
    "GetCustomerPricePreviewOnly": False
  },
  "CustomerPrice": {
    "CurrencyId": "USD",
    "IsGross": True,
    "Value": 4
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
}
conn.request("POST", "/subscription/updatesubscriptionitemprice?ProductId=293039", 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?ProductId=293039',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
  },
  body: JSON.stringify({
    "SubscriptionId": "S67890819",
    "RunningNumber": 1,
    "UpdateAction": "upgrade",
    "Quantity": 300,
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
      "CurrencyId": "USD",
      "IsGross": true,
      "Value": 4
    }
  })

};
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?ProductId=293039")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"SubscriptionId\": \"S67890819\",\n    \"RunningNumber\": 1,\n    \"UpdateAction\": \"upgrade\",\n    \"Quantity\": 300,\n    \"AlignmentSettings\": {\n      \"AlignToCurrentInterval\": false,\n      \"GetCustomerPricePreviewOnly\": false\n    },\n    \"CustomerPrice\": {\n            \"CurrencyId\": \"USD\",\n            \"IsGross\": true,\n            \"Value\": 4.00\n    }\n  }")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 1200.00,
    "NextBillingCustomerNetPrice": 1008.40,
    "NextBillingCustomerVatPrice": 191.60,
    "NextRenewalCustomerGrossPrice": 1200.00,
    "NextRenewalCustomerNetPrice": 1008.40,
    "NextRenewalCustomerVatPrice": 191.60,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/>The customer wants to increase the number of subscription seats and asks for a discount&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><i>Update Subscription Item Price</i> endpoint used&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/>Cleverbridge  automatically bills the customer for the annual renewal&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor