Overview

This guide explains how to use the Update Subscription Item and Renew Subscription API endpoints to renew a subscription before the end of its billing period.

Use case

The customer decides to renew their subscription ahead of the end of the billing period.
On the Self-Service page, the customer clicks the Renew button which uses the Update Subscription endpoint to obtain and display the price, new expiration date, and other details.
After reviewing this information, the customer clicks the Buy Now button to confirm the purchase. The page uses the Renew Subscription endpoint to renew the subscription ahead of the end of the billing period.

Implement API Endpoints

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 Automatic renewal type, which does not require the customer to initiate the renewal at the end of the billing interval.
The current billing interval has started and the next billing date has not been reached yet.
The renewal is not combined with an alignment of the subscription. For more information, see Get Started with Subscriptions > Alignment Settings.
The call using the Renew Subscription API endpoint must be made between the start of the current billing interval and the next billing date.
By default, the Cleverbridge platform bills the customer the full price for the next billing interval, which starts immediately. Any remaining time from the current billing interval is added to the next billing interval, moving the next billing date further into the future. If you want to suppress this behavior, set ResetBillingInterval to true.

Step1: Preview price and new expiration date

In the first call, use the Update Subscription Item endpoint to preview price and new expiration date.

The parameters listed in the table:

Calculate the next billing date if the renewal is made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Do not change any data in the Cleverbridge system

Parameters

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	AlignToCurrentInterval: false GetCustomerPricePreviewOnly: true	Alignment settings used for the price preview calculation.
ProductId	int	Yes	292973	Product ID of the subscription item.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	1	Total number of items in the subscription after the update.
SubscriptionId	str	Yes	S67661151	The unique identifier of the subscription.
UpdateAction	str	No	update (or 0 for JSON)	The value set does not affect transaction processing. See the note below.
TriggerImmediateRenewal	bool	Yes	true	Triggers a renewal immediately.

Request

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
  "ProductId": 292973,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67661151",
  "UpdateAction": 0,
  "TriggerImmediateRenewal": true,
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": true
  }
}'

import http.client
import json

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

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
  },
  body: JSON.stringify({
    "ProductId": 292973,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S67661151",
    "UpdateAction": 0,
    "TriggerImmediateRenewal": true,
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": true
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/updatesubscriptionitem")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n  \"ProductId\": 292973,\n  \"Quantity\": 1,\n  \"RunningNumber\": 1,\n  \"SubscriptionId\": \"S67661151\",\n  \"UpdateAction\": 0,\n  \"TriggerImmediateRenewal\": true,\n  \"AlignmentSettings\": {\n    \"AlignToCurrentInterval\": false,\n    \"GetCustomerPricePreviewOnly\": true\n  }\n} ")
  .asString();

JSON Payload

{
  "ProductId": 292973,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67661151",
  "UpdateAction": 0,
  "TriggerImmediateRenewal": true,
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": true
  }
}

Response

{
    "NextBillingDate": "2026-04-18T16:59:11.003593",
    "NextRenewalDate": "2026-04-18T16:59:11.003593",
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 5.0,
    "NextBillingCustomerNetPrice": 4.20,
    "NextBillingCustomerVatPrice": 0.80,
    "NextRenewalCustomerGrossPrice": 5.0,
    "NextRenewalCustomerNetPrice": 4.20,
    "NextRenewalCustomerVatPrice": 0.80,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Step 2: Renew subscription for another billing interval

In the second API call, use the Renew Subscription API endpoint and the parameters listed in the table to update the customer's subscription data in the Cleverbridge platform.

Parameter	Type	Required	Example	Notes
SubscriptionId	str	Yes	S67661151	The unique identifier of the subscription.
ResetBillingInterval	bool	Yes	false	Set to true to immediately start the new billing interval

📘
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 'https://rest.cleverbridge.com/subscription/renewsubscription' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
    "SubscriptionId": "S67661151",
    "ResetBillingInterval": false
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S67661151",
  "ResetBillingInterval": False
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
}
conn.request("POST", "/subscription/renewsubscription", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest.cleverbridge.com/subscription/renewsubscription',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
  },
  body: JSON.stringify({
    "SubscriptionId": "S67661151",
    "ResetBillingInterval": true
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/renewsubscription")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"SubscriptionId\": \"S67661151\",\n    \"ResetBillingInterval\": false\n}")
  .asString();

Response

{
    "ContinueUrl": "https://www.cleverbridge.com/864/p/534595860-oXFDYs788AiQXLEZsiKU",
    "NextBillingDate": "2026-04-11T13:45:22.830752",
    "TransactionStatus": "Success",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/>The customer decides to renew their subscription ahead of the end of the billing period&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><i>Update Subscription Item</i> endpoint is used to obtain and display the price, new expiration date, and other details&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><i>Renew Subscription</i> endpoint is used after the customer confirms the purchase and clicks the <b>Buy Now</b> button&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor