Overview

This guide shows you how to implement the Update Subscription Item Price API endpoint to do increase the customer's subscription renewal price.

Use Case

December 20: Cleverbridge bills the customer $15.95 for their monthly subscription.
January 1: The customer receives an email notification asking them to accept or decline a price increase.
January 5: The customer accepts the price increase. The subscription is updated using the Update Subscription Item API endpoint.
January 20: Cleverbridge automatically bills the customer $19.95 for the monthly subscription at the new price. Implement API endpoint

Implement API endpoint

Before you start

🚧
Important
Get the customer's consent for changes to subscriptions. 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.

Makes sure that:

The subscription has the status Active.
The price increase takes place at the time of the next billing interval.
Any price changes made apply to all future billing events unless changed subsequently.

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

Parameters

Set the parameters in the Update Subscription Item API call to the values listed in the table.

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	`AlignToCurrentInterval: false GetCustomerPricePreviewOnly: false`	The subscription is changed as requested in the API call.
ProductId	int	Yes	293039	Product ID for the higher priced product (not the current product being replaced).
RunningNumber	int	Yes	1	Running number of the item in the subscription.
SubscriptionId	str	Yes	S67439867	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)

Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.
Use the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.

Request

curl -X POST "https://rest.cleverbridge.com/subscription/updatesubscriptionitem" \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{
    "SubscriptionId": "S67439867",
    "RunningNumber": 1,
    "ProductId": 293039,
    "UpdateAction": "upgrade",
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": false
    }
  }'

import requests

url = "https://rest.cleverbridge.com/subscription/updatesubscriptionitem"

payload = {
    "SubscriptionId": "S67439867",
    "RunningNumber": 1,
    "ProductId": 293039,
    "Quantity": 1,                 # REQUIRED
    "UpdateAction": "Upgrade",     # Use enum string: Update / Upgrade / Downgrade
    "AlignmentSettings": {
        "AlignToCurrentInterval": False,
        "GetCustomerPricePreviewOnly": False
    }
}


headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "authorization": "Basic YOUR_BASE64_ENCODED_CREDENTIALS"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const https = require("https");

const payload = JSON.stringify({
  SubscriptionId: "S67439867",
  RunningNumber: 1,
  ProductId: 293039,
  UpdateAction: "upgrade",
  AlignmentSettings: {
    AlignToCurrentInterval: false,
    GetCustomerPricePreviewOnly: false
  }
});

const options = {
  hostname: "rest.cleverbridge.com",
  path: "/updatesubscriptionitemprice",
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_BASE64_ENCODED_CREDENTIALS",
    "Content-Type": "application/json",
    "Content-Length": Buffer.byteLength(payload)
  }
};

const req = https.request(options, res => {
  let responseBody = "";
  res.on("data", chunk => responseBody += chunk);
  res.on("end", () => console.log(responseBody));
});

req.on("error", console.error);
req.write(payload);
req.end();

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class UpdateSubscriptionItemPrice {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://rest.cleverbridge.com/updatesubscriptionitemprice");
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        connection.setRequestMethod("POST");
        connection.setRequestProperty("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS");
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setDoOutput(true);

        String payload = """
        {
          "SubscriptionId": "S67439867",
          "RunningNumber": 1,
          "ProductId": 293039,
          "UpdateAction": "upgrade",
          "AlignmentSettings": {
            "AlignToCurrentInterval": false,
            "GetCustomerPricePreviewOnly": false
          }
        }
        """;

        try (OutputStream os = connection.getOutputStream()) {
            os.write(payload.getBytes(StandardCharsets.UTF_8));
        }

        int status = connection.getResponseCode();
        System.out.println("HTTP Status: " + status);
    }
}

Response

{
  "AlignmentCustomerGrossPrice":0.0,
  "AlignmentCustomerNetPrice":0.0,
  "AlignmentCustomerVatPrice":0.0,
  "NextBillingCustomerGrossPrice":19.95,
  "NextBillingCustomerNetPrice":16.76,
  "NextBillingCustomerVatPrice":3.19,
  "NextRenewalCustomerGrossPrice":19.95,
  "NextRenewalCustomerNetPrice":16.76,
  "NextRenewalCustomerVatPrice":3.19,
  "PriceCurrencyId":"USD",
  "ResultMessage":"OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>December 20</b><br/>Cleverbridge bills the customer $15.95<br/>for the  subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>January 1</b><br/>The customer receives an email <br/>to accept or decline price increase&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>January 5</b><br/>The customer accepts.<br/>The subscription is updated using the<br/><i>Update Subscription Item</i> API&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> D(["&nbsp;&nbsp;<br/><b>January 20</b><br/>Cleverbridge automatically bills the customer&nbsp;<br/>&nbsp;"]):::mainColor