Overview

This guide shows you how to implement Update Subscription Item endpoint to change the billing interval of a single-item subscription.

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

Use Case

A customer converts from a freemium subscription product to a paid subscription in the Cleverbridge system. The client must have agreed to a processing fee for freemium subscriptions, and the customer must enter payment details during the initial purchase.

On January 1st, a customer uses the Cleverbridge checkout process to purchase your company's Freemium subscription to a photo upload and sharing service that includes up to 10 gigabytes of storage space.
On July 1st, the customer would like additional storage space, and subscribes to the Paid service for $25 annually. The customer visits a client-hosted page to upgrade the subscription. You use the Update Subscription Item endpoint to replace the Freemium product with the Paid product.
The Cleverbridge platform automatically bills the customer a pro-rated amount for the rest of the billing interval.
On July 1st of the following year, the Cleverbridge platform automatically bills the customer $25 for the Premium plan for the new annual billing interval.

Implement Update Subscription Item endpoint

Before you start

Make sure that:

The subscription contains only a single item, and is effective at the time of the next billing date.
Both the Freemium and Paid subscription products are set up in the Cleverbridge platform.
The billing interval for the Freemium subscription product and the Paid subscription product are the same (in this use case, annually).
The customer's payment information was captured during a past purchase.
The Freemium subscription has the status Active.
The renewal date for the Paid subscription will be based on the date that the customer purchased the Freemium subscription.
Changes made by this function, including the price and/or quantity, apply to all future billing events unless changed subsequently.
If a client adds a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

📘
Note
To replace one subscription item with another, the original and the replacement items must have the same currency and billing interval. If you want to change the billing interval of a subscription, this will only be effective at the time of the next billing date.

Parameters

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

Parameter	Type	Required	Example
ProductId	integer	Yes	29899
Quantity	integer	Yes	1
RunningNumber	integer	Yes	1
SubscriptionId	string	Yes	284947
UpdateAction	integer	No	upgrade
AlignmentSettings	object	Yes	`AlignToCurrentInterval: false GetCustomerPricePreviewOnly: false`
CustomerPrice	object	No	`{ "CurrencyId": "EUR", "IsGross": true, "Value": 9.99 }`

To find out more about parameters, see:

📘
Note
Use /getsubscription endpoint to retrieve ProductId.

📘
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)

Request

curl --location --request POST 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
  "ProductId": 29899,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "284947",
  "UpdateAction": "upgrade"
}'

import base64
import json
import requests

# --- Configuration ---
url = "https://rest.cleverbridge.com/subscription/updatesubscriptionitem"
username = "myuser"
password = "mypassword"

# Encode credentials to Base64 for Basic Auth
credentials = f"{username}:{password}"
encoded_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")

# --- Headers ---
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": f"Basic {encoded_credentials}"
}

# --- JSON Payload ---
payload = {
    "ProductId": 29899,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "284947",
    "UpdateAction": "upgrade"
}

# --- Request ---
response = requests.post(url, headers=headers, data=json.dumps(payload))

# --- Response Handling ---
print("Status Code:", response.status_code)
try:
    print("Response JSON:", response.json())
except ValueError:
    print("Response Text:", response.text)

const axios = require('axios');

// Replace with your Base64 encoded credentials (e.g., 'Basic dXNlcjpwYXNz')
const authHeader = 'Basic YOUR_BASE64_ENCODED_CREDENTIALS';

// Request payload
const data = {
  ProductId: 29899,
  Quantity: 1,
  RunningNumber: 1,
  SubscriptionId: "284947",
  UpdateAction: "upgrade"
};

// API endpoint
const url = 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem';

(async () => {
  try {
    const response = await axios.post(url, data, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': authHeader
      }
    });
    console.log('Response:', response.data);
  } catch (error) {
    console.error('Error:', error.response ? error.response.data : error.message);
  }
})();

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

public class UpdateSubscriptionItem {
    public static void main(String[] args) {
        String urlString = "https://rest.cleverbridge.com/subscription/updatesubscriptionitem";
        String authHeader = "Basic YOUR_BASE64_ENCODED_CREDENTIALS";
        String jsonInputString = """
        {
          "ProductId": 29899,
          "Quantity": 1,
          "RunningNumber": 1,
          "SubscriptionId": "284947",
          "UpdateAction": "upgrade"
        }
        """;

        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Authorization", authHeader);
            conn.setDoOutput(true);

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            int code = conn.getResponseCode();
            System.out.println("Response Code: " + code);
            // Optionally read the response body here

            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 9.99,
    "NextBillingCustomerNetPrice": 8.39,
    "NextBillingCustomerVatPrice": 1.60,
    "NextRenewalCustomerGrossPrice": 9.99,
    "NextRenewalCustomerNetPrice": 8.39,
    "NextRenewalCustomerVatPrice": 1.60,
    "PriceCurrencyId": "EUR",
    "ResultMessage": "OK"
}

Customer Converts from Freemium to Paid Subscription

Overview

Use Case

Implement Update Subscription Item endpoint

Before you start

Parameters

Note

Note

Request

Response

Diagram