Overview

This guide shows you how to implement the Update Subscription Item Price endpoint to upgrade a subscription starting with the next billing cycle.

Use case

The price for Cloudify Gold Subscription goes up from $95.19 to $100.00

Cloudify increases the price of its subscription plans and notifies customers via email of the price increase in 30 days in advance of the renewal.
After the customer accepts the new price, the application uses the Update Subscription Item Price endpoint to apply the updated pricing to the subscription.
The Cleverbridge platform automatically bills the customer the new price starting with the next billing cycle .

Implement the Update Subscription Item Price endpoint

Before you start

Make sure that:

The subscription has the status Active.
The price update takes place on the next renewal date.
All other subscription properties that have an effect on the price, such as product or quantity, remain the same.

🚧
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.

Parameters

To achieve this particular use case, set the parameters in the Update Subscription Item Price API call to the values listed in the table.

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	AlignToCurrentInterval: false GetCustomerPricePreviewOnly: false	The subscription is changed as requested in the API call.
CustomerPrice	obj	Yes	`{ "CurrencyId": "USD", "IsGross": true, "Value": 100.00 }`	Pricing information that the customer receives during the purchase process.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	1	Total number of items after the update.
SubscriptionId	str	Yes	S67439867	The unique identifier of the subscription.
UpdateAction	str	No	upgrade	The value set does not affect transaction processing.

📘
Note
Do not use ForcePriceRecalculation together with CustomerPrice parameter. ForcePriceRecalculation replaces the subscription item's price with the current product price configured in Cleverbridge, causing any customer-specific price values in the request to be ignored.

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": false,
        "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice": {
        "CurrencyId": "USD",
        "IsGross": true,
        "Value": 100.00
    }
}'

import http.client
import json

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

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\": false,\n        \"GetCustomerPricePreviewOnly\": false\n    },\n    \"CustomerPrice\": {\n        \"CurrencyId\": \"USD\",\n        \"IsGross\": true,\n        \"Value\": 100.00\n    }\n}")
  .asString();

JSON body

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

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 100.00,
    "NextBillingCustomerNetPrice": 84.03,
    "NextBillingCustomerVatPrice": 15.97,
    "NextRenewalCustomerGrossPrice": 100.00,
    "NextRenewalCustomerNetPrice": 84.03,
    "NextRenewalCustomerVatPrice": 15.97,
    "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 annoucement</b><br/>Cloudify increases prices and notifies customers via email&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Price increase imlementation</b><br/><i>Update subscription item price</i> endpoint used to apply the price increase&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Billing</b><br/>The Cleverbridge platform automatically bills the customer the increased price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor