Overview

This guide shows you how to implement the Update Subscription Item Price API endpoint to renew quantity of users and price.

Apply a price and quantity change effective with the next renewal.

Use case

Before the renewal, a customer is offered a new monthly price depending on the number of seats (licenses):

Total Desktop Licenses	Per-License Renewal Price
Less than 100	$5.00
100 – 499	$4.00
500 or more	$3.00

For the previous billing interval, the customer was billed $3,500.00 for 700 desktop licenses at $5.00 each.
The customer decides to renew only 400 licenses.
Update Subscription Item Price API endpoint updates the desktop license quantity and price for the customer’s subscription.

Renewal price for 400 license renewals: 400 x 4.00 = 1600

After reviewing the renewal price and quantity, the customer confirms that they want to proceed. The page uses the Update Subscription Item Price API endpoint to update the desktop license quantity and price for the customer’s subscription in the Cleverbridge platform.
Cleverbridge automatically bills the customer $1600 for the next monthly billing interval.

Implement Update Subscription Item Price endpoint

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.

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`	The subscription is changed as requested in the API call. For more details, see Alignment Settings.
CustomerPrice	obj	Yes	`CurrencyId: USD` `IsGross: true` `Value: 4.00`	For more details, see * Understand Customer Price .
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	400	Total number of items after the update.
SubscriptionId	str	Yes	S67902097	The unique identifier of the subscription.
UpdateAction	str	No	downgrade	The value set does not affect transaction processing.

JSON body

{
    "SubscriptionId": "S67902097",
    "RunningNumber": 1,
    "Quantity": 400,
    "UpdateAction": "downgrade",
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
        "CustomerPrice": {
            "CurrencyId": "USD",
            "IsGross": true,
            "Value": 4.00
    }
  }

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": "S67902097",
    "RunningNumber": 1,
    "Quantity": 400,
    "UpdateAction": "downgrade",
    "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": "S67902097",
  "RunningNumber": 1,
  "Quantity": 400,
  "UpdateAction": "downgrade",
  "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", 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": "S67902097",
  "RunningNumber": 1,
  "Quantity": 400,
  "UpdateAction": "downgrade",
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": false
  },
  "CustomerPrice": {
    "CurrencyId": "USD",
    "IsGross": true,
    "Value": 4
  }
});

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\": \"S67902097\",\n    \"RunningNumber\": 1,\n    \"Quantity\": 400,\n    \"UpdateAction\": \"downgrade\",\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": 1600.00,
    "NextBillingCustomerNetPrice": 1344.54,
    "NextBillingCustomerVatPrice": 255.46,
    "NextRenewalCustomerGrossPrice": 1600.00,
    "NextRenewalCustomerNetPrice": 1344.54,
    "NextRenewalCustomerVatPrice": 255.46,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/>Customer selects quantity of licenses&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>Merchant calculates tier-based price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><i>Update Subscription Item Price</i> API updates subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> D(["&nbsp;&nbsp;<br/>Cleverbridge bills for the next monthly renewal&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor