Overview

This guide shows you how to use the Get Subscription and Update Subscription Item API endpoints to retrieve a subscription's current billing information and then apply an update that adds an additional seat.

Use case

A customer purchased a Cloudify Storage subscription with one seat on May 21, 2026. The subscription renews monthly for $100.00, with the next billing and renewal date on June 21, 2026.
Cloudify offers the customer an additional seat for $80.00 per month if the customer immediately extends the subscription term by six months.
On the Customer Self-Service page, the application calls the Get Subscription API endpoint to retrieve the current NextBillingDate.
After reviewing the offer, the customer clicks Buy Now.
The application calls the Update Subscription Item API endpoint to apply the subscription update.

Result

The customer now has two active seats that renew together on December 21, 2026.

Implement the API endpoints

Use two API calls to retrieve the current subscription details and then apply the update:

Call the Get Subscription API endpoint to retrieve the current subscription details, including the current NextBillingDate.
Call the Update Subscription Item API endpoint after the customer accepts the offer. This call increases the quantity from one seat to two seats and applies the alignment settings specified in the request.

The first call is read-only. It retrieves the customer's current subscription data and does not change the subscription.

Before you start

This example assumes that the subscription contains a single current subscription item.

Make sure that:

The subscription has the status Active.
The discounted promotional price is already configured in the Cleverbridge platform.
The original and updated subscription items use the same currency and billing interval.
Any changes made, including the price and/or quantity, apply to the current and all future billing events unless modified later.
If the subscription item is updated, a history of revisions is created automatically. Confirm that the current version receives the update.

For more information on which API endpoint to use, see Guidelines for When to Use UpdateSubscriptionItem vs. UpdateSubscriptionItemPrice.

🚧
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: Retrieve the current subscription details and next billing date

Call the Get Subscription API endpoint to retrieve the customer's current subscription details. The response includes the NextBillingDate, which you can display to the customer before they accept the offer.

Parameters

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

Request

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

Response

{
  "Subscription": {
    "Id": 68952510,
    "NextBillingDate": "2026-06-21T12:53:44.776988",
    "RenewalType": "Automatic",
    "Subscriptionstatus": 1,
    "Items": [
      {
        "RunningNo": 1,
        "ProductId": 293103,
        "ProductName": "Cloudify Storage Monthly Renewal",
        "ProductNameExtension": "Cloud Storage",
        "Quantity": 1,
        "Status": 1,
        "NextBillingCustomerGrossPrice": 100.0
      }
    ]
  },
  "ResultMessage": "OK"
}

Step 2: Apply the subscription update

After the customer accepts the offer, call the Update Subscription Item API endpoint to update the subscription item.

In this sample, the request updates the subscription from one seat to two seats. The Quantity value represents the total number of seats after the update.

The update request uses ExtendInterval = true to extend the subscription term by six months while increasing the quantity to two seats.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	AlignToCurrentInterval: true GetCustomerPricePreviewOnly: false ExtendInterval: true	Controls how the subscription update is applied, including interval alignment, term extension, and preview behavior.
ProductId	int	Yes	293103	Product ID of the subscription item.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	2	Total number of items after the update.
SubscriptionId	str	Yes	S68952510	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:

For upgrades, set the parameter to upgrade (or 1 in JSON).

For downgrades, set the parameter to downgrade (or 2 in JSON).

For all other changes, set the parameter to update (or 0 in JSON).

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,
    "RunningNumber": 1,
    "SubscriptionId": "S68952510",
    "UpdateAction": 1,
    "Quantity": 2,
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": false,
				"ExtendInterval": true
    }
}'

import http.client
import json

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

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    \"RunningNumber\": 1,\n    \"SubscriptionId\": \"S68952510\",\n    \"UpdateAction\": 1,\n    \"Quantity\": 2,\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": true,\n        \"GetCustomerPricePreviewOnly\": false,\n        \"ExtendInterval\": true\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 180.0,
    "NextBillingCustomerNetPrice": 151.26,
    "NextBillingCustomerVatPrice": 28.74,
    "NextRenewalCustomerGrossPrice": 180.0,
    "NextRenewalCustomerNetPrice": 151.26,
    "NextRenewalCustomerVatPrice": 28.74,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>Promotional offer sent</b><br/>The customer receives an offer to buy an additional seat<br/>at a discounted price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Customer Self-Service</b><br/><i>Get Subscription</i> retrieves the current <code>NextBillingDate</code><br/>and subscription details&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Purchase confirmation</b><br/>The customer clicks <b>Buy Now</b>.<br/><i>Update Subscription Item</i> extends the subscription<br/>and applies the seat update&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor