Overview

This guide shows you how to implement the Deactivate Subscription Items endpoint to retire subscriptions for a discontinued product and prevent customers from reactivating their subscriptions.

Use case

Cloudify decides to discontinue its Cloudify S product.
Cloudify informs all affected customers that their subscriptions will not renew after the current billing interval ends.
To prevent customers from reactivating the discontinued product through old links or previous order confirmations, Cloudify deactivates the subscription item from all active subscriptions.
The page or internal application uses the Deactivate Subscription Items endpoint to permanently remove the discontinued subscription item.

Result

The Cleverbridge platform moves the subscription to the Finished status and prevents future reactivation of the discontinued product.

📘
Finished Status
Finished status means that all required rebilling events are complete for a subscription, often set up with the option to end the subscription after a certain number of billing events.

Implement API endpoints

Before you start

Make sure that:

The subscription has the status Active.
All communication about the product discontinuation is handled by your company.
The discontinued product should no longer be available for reactivation or renewal.
You understand that removing a subscription item permanently deletes the item and its associated subscription data.

👍
Tip
It is recommended to use the Deactivate Subscription Items endpoint instead of the Remove Subscription Item endpoint, because it retains subscription information while preventing future billing.

🚧
Important
Get the customer's consent before making changes to a subscription. For more information, see Best Practices: Obtain Customer Consent.

Step 1: Get the subscription details

Use the Get Subscription endpoint to retrieve the current subscription details and identify the subscription item to deactivate.

Parameters

Parameter	Type	Required	Example	Notes
SubscriptionId	str	Yes	S67458907	The unique identifier of the subscription.

Request

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

import requests

url = "https://rest.cleverbridge.com/subscription/getsubscription?subscriptionId=S67458907"

payload = {}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

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

var options = {
  'method': 'GET',
  'hostname': 'rest.cleverbridge.com',
  'path': '/subscription/getsubscription?subscriptionId=S67458907',
  '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=S67458907")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .asString();

{
  "SubscriptionId": "S67458907"
}

Response

{
  "Subscription": {
    "Id": 67645948,
    "Items": [
      {
        "RunningNo": 1,
        "ProductName": "Cloudify S",
        "Status": 1
      }
    ]
  },
  "ResultMessage": "OK"
}

Step 2: Deactivate Subscription Items

Use the Deactivate Subscription Items endpoint to deactivate the discontinued subscription item.

Parameters

Parameter	Type	Required	Example	Notes
SubscriptionId	str	Yes	S67458907	The unique identifier of the subscription.
Items	int	Yes	1	The running number of the subscription item to remove.
AllowReinstate	bool	Yes	true	Set to `true` if you want to be able to reinstate items at a later date. If set to `false`, the item status changes to `Finished`
GenerateMail	bool	Yes	false	Set to false if you want to suppress the automatically generated email that informs the customer about the subscription update.

Request

curl --location 'https://rest.cleverbridge.com/subscription/deactivatesubscriptionitems' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
  "Items": [
    1
  ],
  "SubscriptionId": "S67645948",
  "AllowReinstate": false,
  "GenerateMail": false
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "Items": [
    1
  ],
  "SubscriptionId": "S67645948",
  "AllowReinstate": False,
  "GenerateMail": False
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/deactivatesubscriptionitems", 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': 'POST',
  'hostname': 'rest.cleverbridge.com',
  'path': '/subscription/deactivatesubscriptionitems',
  '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 (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

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

var postData = JSON.stringify({
  "Items": [
    1
  ],
  "SubscriptionId": "S67645948",
  "AllowReinstate": false,
  "GenerateMail": false
});

req.write(postData);

req.end();

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://rest.cleverbridge.com/subscription/deactivatesubscriptionitems")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n  \"Items\": [\n    1\n  ],\n  \"SubscriptionId\": \"S67645948\",\n  \"AllowReinstate\": false,\n  \"GenerateMail\": false\n}")
  .asString();

{
  "Items": [
    1
  ],
  "SubscriptionId": "S67645948",
  "AllowReinstate": false,
  "GenerateMail": false
}

Response

{
    "ResultMessage": "OK"
}