Overview

This guide shows you how to switch a subscription to manual renewal using the Update Subscription Renewal Type API endpoint.

Use Case

Cloudify wants customers to control their own renewal settings from a self-service account portal. A customer clicks Turn off automatic renewal in their account settings.

Cloudify's backend receives the request from the portal.
Cloudify's backend calls the Update Subscription Renewal Type endpoint.
Cleverbridge updates the subscription and sends a SubscriptionRenewalTypeChangedNotification.
Cloudify's backend updates the subscription record in its CRM.

Result

The subscription no longer renews automatically. The customer must initiate future renewals manually.

Diagram

Implement the Update Subscription Renewal Type endpoint

Call this endpoint once to change how a subscription renews.

Before you start

Make sure that:

Your notification endpoint can receive a SubscriptionRenewalTypeChangedNotification, so your local systems stay in sync after the change. The Update Subscription Renewal Type feature must also be enabled for your account. To enable it, contact your Client Experience Manager.

📘
Configure notifications
To receive this notification, add and configure a notification.

Step 1: Call Update Subscription Renewal Type endpoint

Include the customer's SubscriptionId in the API call and indicate that RenewalType should be changed to Manual.

Parameters

Parameter	Type	Required	Example	Notes
`SubscriptionId`	string	Yes	`S64591315`	Unique ID of the subscription. Include or omit the leading `S`.
`RenewalType`	string	Yes	`Manual`	New renewal type. Allowed values: `Manual`, `Automatic`.

Request

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionrenewaltype' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
  "RenewalType": "Manual",
  "SubscriptionId": "S64591315"
}'

import http.client
import json

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

async function main() {
  const response = await fetch('https://rest.cleverbridge.com/subscription/updatesubscriptionrenewaltype', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
    },
    body: JSON.stringify({
      RenewalType: 'Manual',
      SubscriptionId: 'S64591315'
    })
  });

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  console.log(await response.text());
}

main().catch(console.error);

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

public class Main {
  public static void main(String[] args) throws Exception {
    String requestBody = "{"
        + "\"RenewalType\":\"Manual\","
        + "\"SubscriptionId\":\"S64591315\""
        + "}";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://rest.cleverbridge.com/subscription/updatesubscriptionrenewaltype"))
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
        .POST(HttpRequest.BodyPublishers.ofString(requestBody))
        .build();

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

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

Response

{
  "ResultMessage": "OK"
}

ResultMessage confirms the update succeeded.

Step 2: Receive the SubscriptionRenewalTypeChangedNotification

Cleverbridge sends you a SubscriptionRenewalTypeChangedNotification, which contains information that allows you to update your local ecosystem (CRM, ERP, etc.). It includes:

Parameter	Description
`subscriptionId`	The Cleverbridge subscription ID
`renewalType`	Whether the subscription now has an `Automatic` or `Manual` renewal type

{
  "meta": {
    "type": "SubscriptionRenewalTypeChangedNotification"
  },
  "items": [{
    "recurringBilling": {
      "subscriptionId": "S64591315",
      "renewalType": "Manual"
    }
  }]
}