Overview

This guide shows you how to implement the Update Subscription Item endpoint to change a subscription’s billing interval from shorter to longer, effective on the next billing date.

Use case

On May 8th, a customer clicks through an email reminder to manually renew an annual Cloudify subscription, which has a monthly billing interval, by the July 1st renewal date.
The email redirects the customer to a landing page that displays the following options:

This image is for illustration purpose only

The customer selects the annual renewal option
The Update Subscription Item endpoint is used to change to the product billed annually.
On July 1st, the Cleverbridge platform automatically charges the customer $900 for the next annual billing interval.

Implement Update Subscription Item endpoint

Before you start

Make sure that the subscription:

has the status Active
contains only a single item
is effective at the time of the next billing date
renews annually

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

Parameters

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	293104	Product ID for the new product: the ID of the product with an annual billing interval.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
SubscriptionId	str	Yes	S67632293	The unique identifier of the primary subscription.
UpdateAction	str	No	upgrade	The value set does not affect transaction processing. See the note below.

Changes made by this function, including the price and/or quantity, apply to all future billing events unless changed subsequently.
Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.
Use of the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.
When you add a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

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

📘
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 -X POST "https://rest.cleverbridge.com/subscription/updatesubscriptionitem?SubscriptionId=S67204221&ProductId=292124&Quantity=1&RunningNumber=1&UpdateAction=upgrade" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS" \
  -d '{
    "ProductId": 293104,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S67632293",
    "UpdateAction": 0,
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": true
    }
  }'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "ProductId": 293104,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67632293",
  "UpdateAction": 0,
  "AlignmentSettings": {
    "AlignToCurrentInterval": False,
    "GetCustomerPricePreviewOnly": True
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/updatesubscriptionitem?SubscriptionId=S67204221&ProductId=292124&Quantity=1&RunningNumber=1&UpdateAction=upgrade", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

const https = require('https');

const data = JSON.stringify({
  ProductId: 293104,
  Quantity: 1,
  RunningNumber: 1,
  SubscriptionId: "S67632293",
  UpdateAction: 0,
  AlignmentSettings: {
    AlignToCurrentInterval: false,
    GetCustomerPricePreviewOnly: true
  }
});

const options = {
  hostname: 'rest.cleverbridge.com',
  path: '/subscription/updatesubscriptionitem?SubscriptionId=S67204221&ProductId=292124&Quantity=1&RunningNumber=1&UpdateAction=upgrade',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let responseBody = '';

  res.on('data', (chunk) => {
    responseBody += chunk;
  });

  res.on('end', () => {
    console.log(responseBody);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class UpdateSubscriptionItem {
    public static void main(String[] args) throws Exception {

        String json = """
        {
          "ProductId": 293104,
          "Quantity": 1,
          "RunningNumber": 1,
          "SubscriptionId": "S67632293",
          "UpdateAction": 0,
          "AlignmentSettings": {
            "AlignToCurrentInterval": false,
            "GetCustomerPricePreviewOnly": true
          }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://rest.cleverbridge.com/subscription/updatesubscriptionitem?SubscriptionId=S67204221&ProductId=292124&Quantity=1&RunningNumber=1&UpdateAction=upgrade"))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

Response

{
  "AlignmentCustomerGrossPrice": 0,
  "AlignmentCustomerNetPrice": 0,
  "AlignmentCustomerVatPrice": 0,
  "NextBillingCustomerGrossPrice": 900,
  "NextBillingCustomerNetPrice": 756.3,
  "NextBillingCustomerVatPrice": 143.7,
  "NextRenewalCustomerGrossPrice": 900,
  "NextRenewalCustomerNetPrice": 756.3,
  "NextRenewalCustomerVatPrice": 143.7,
  "PriceCurrencyId": "USD",
  "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>May 8th</b><br/>Customer selects the annual renewal option&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><i>Update Subscription Item</i><br/>changes to the product billed annually&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>July 1st</b><br/>Cleverbridge  bills the customer $900&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor