Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus

Upgrade a Subscription Effective Next Billing Date

Overview

This guide shows you how to implement the Update Subscription Item endpoint to allow a customer to upgrade a subscription effective with the next billing date.

Use case

  1. A customer's Cloudify Gold subscription renews at $100.00 per month.
  2. Cloudify sends Gold customers a promotional email offering a discounted upgrade if they upgrade their subscription within the next five days.
    This discount offers the Platinum subscription for $135 instead of $150.00 monthly.
  3. The customer clicks a link in the promotional email that displays a landing page you created for the promotion.
  4. The customer enters the subscription ID and clicks the Buy Now button to accept the upgrade. The landing page calls the following endpoints:

Result

The Cleverbridge platform upgrades the customer to the Platinum subscription and bills $135.00 on the next billing date and all subsequent renewal dates.

Implement the Update Subscription Item endpoint

Before you start

Make sure that:

  • The subscription has the status Active.
  • The product to which the customer wants to upgrade has been set up in the Cleverbridge platform.
  • Both products have the same billing interval.
🚧

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 customer's current subscription details

Call the Get Subscription endpoint to obtain the customer's current subscription details.

Parameters

ParameterTypeRequiredExampleNotes
SubscriptionIdstrYesS67645948The unique identifier of the subscription

Request

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

Response

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

The response confirms the customer's current subscription item and provides the RunningNo needed in Step 2. It also shows the current renewal price of $100.00, which is replaced with the promotional renewal price of $135.00 when the upgrade is applied.

Step 2: Complete the upgrade to the Platinum subscription

Call the Update Subscription Item endpoint to replace the Gold subscription item with the Platinum subscription item and set the promotional renewal price.

Parameters

Parameter

Type

Required

Example

Notes

AlignmentSettings

obj

Yes

AlignToCurrentInterval: false,
GetCustomerPricePreviewOnly: false

The subscription is changed as requested in the API call.
AlignToCurrentInterval=false ensures the upgrade takes effect on the next billing date and does not generate an immediate alignment charge.

CustomerPrice

obj

"CurrencyId":"USD"
"IsGross":true "Value":135.00

Defines a custom price for the subscription item that overrides the product’s default price for future billing events.

ProductId

int

Yes

294581

Product ID for the Platinum product (not the current product being replaced).

RunningNumber

int

Yes

1

Running number of the item in the subscription.

SubscriptionId

str

Yes

S67645948

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)

JSON body

{
    "ProductId": 294581,
    "RunningNumber": 1,
    "Quantity": 1,
    "SubscriptionId": "S67439867",
    "UpdateAction": 1,
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 135.00
    },
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    }
}

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": 294581,
    "RunningNumber": 1,
    "Quantity": 1,
    "SubscriptionId": "S67439867",
    "UpdateAction": 1,
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 135.00
    },
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": false
    }
}'
import http.client
import json

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

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\": 294581,\n    \"RunningNumber\": 1,\n    \"Quantity\": 1,\n    \"SubscriptionId\": \"S67439867\",\n    \"UpdateAction\": 1,\n    \"CustomerPrice\": {\n        \"CurrencyId\": \"USD\",\n        \"IsGross\": true,\n        \"Value\": 135.00\n    },\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": false,\n        \"GetCustomerPricePreviewOnly\": false\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 135.00,
    "NextBillingCustomerNetPrice": 113.45,
    "NextBillingCustomerVatPrice": 21.55,
    "NextRenewalCustomerGrossPrice": 135.00,
    "NextRenewalCustomerNetPrice": 113.45,
    "NextRenewalCustomerVatPrice": 21.55,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

The response confirms that no immediate alignment charge was created (AlignmentCustomerGrossPrice = 0.0). Beginning with the next billing date, the customer will be billed $135.00 for the upgraded Platinum subscription instead of the previous $100.00 Gold subscription renewal price.

Diagram


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

  A(["&nbsp;&nbsp;<br/><b>Discount offer</b><br/>Promotional email is sent, offering a Platinum product discounted by 20%&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Customer accepts</b><br/>The customer accepts the offer&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Upgrade</b><br/><i>Update Subscription Item</i> endpoint used to  complete the upgrade&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor