Overview

This guide explains how to use the Get Subscription 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 before the end of the billing period.
On the Self-Service page, the customer clicks Renew. The page calls the Get Subscription endpoint to retrieve the renewal price, new expiration date, and other subscription 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 before 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 status Active.
The subscription has the Automatic renewal type.
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.

Step 1: Preview the renewal price and next billing date

Call the Get Subscription API endpoint to preview the renewal price and updated next billing date before confirming the renewal.

The SubscriptionId parameter lets you:

Calculate the next billing date if the subscription is renewed.
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
SubscriptionId	str	Yes	S67661151	The unique identifier of the subscription.

Request

curl --location 'https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S67661151' 
--header 'Accept: application/json' 
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS'

import http.client

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = ''
headers = {
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS',
}
conn.request("GET", "/subscription/getsubscription?subscriptionId=S67661151", 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': 'GET',
  'hostname': 'rest.cleverbridge.com',
  'path': '/subscription/getsubscription?subscriptionId=S67661151',
  'headers': {
    '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);
  });
});

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.get("https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S67661151")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .asString();

Response

{
  "Subscription": {
    "Id": 67661151,
    "RenewalType": "Automatic",
    "NextBillingDate": "2026-04-13T09:43:08.734828",
    "NextBillingCustomerGrossPrice": 75.00,
    "NextBillingCustomerNetPrice": 63.03,
    "NextBillingCustomerVatPrice": 11.97,
    "Items": [
      {
        "RunningNo": 1,
        "ProductName": "Cloudify Seat",
        "Quantity": 15,
        "Status": 1
      }
    ]
  },
  "ResultMessage": "OK"
}

The response contains the current subscription details together with the renewal price and the NextBillingDate. Display this information to the customer so they can review the renewal before confirming the purchase.

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 renew the subscription for an additional billing interval.

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)

response = conn.getresponse()
print(response.read().decode("utf-8"))

var https = require('follow-redirects').https;

var options = {
  method: 'POST',
  hostname: 'rest.cleverbridge.com',
  path: '/subscription/renewsubscription',
  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 () {
    console.log(Buffer.concat(chunks).toString());
  });

  res.on('error', function (error) {
    console.error(error);
  });
});

req.write(JSON.stringify({
  SubscriptionId: 'S67661151',
  ResetBillingInterval: false
}));

req.end();

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

{
  "Subscription": {
    "Id": 67661151,
    "RenewalType": "Automatic",
    "NextBillingDate": "2026-04-13T09:43:08.734828",
    "NextBillingCustomerGrossPrice": 75.00,
    "NextBillingCustomerNetPrice": 63.03,
    "NextBillingCustomerVatPrice": 11.97,
    "Items": [
      {
        "RunningNo": 1,
        "ProductName": "Cloudify Seat",
        "Quantity": 15,
        "Status": 1
      }
    ]
  },
  "ResultMessage": "OK"
}

The response confirms that the renewal was processed successfully. The NextBillingDate now reflects the renewed subscription according to the value of ResetBillingInterval.

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 before 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