Overview

This guide explains how to preview the prorated price of a subscription add-on, process the customer's confirmation, and update the subscription using the Add Subscription Item Item endpoint.

Implement Add Subscription Item Endpoint

Before you start

Make sure that:

You have credentials for the Cleverbridge REST API.
You know the customer’s SubscriptionId and the add-on ProductId.
You can receive PaidOrderNotification notifications.

Step 1: Preview Prorated Price

Call the Add Subscription Item endpoint to calculate the prorated price for the remainder of the current billing interval.

Parameters

Parameter	Type	Example	Description
`SubscriptionId`	`str`	`"S12345678"`	Identifier of the existing Cleverbridge subscription to which the product will be added.
`ProductId`	`int`	`123456`	Identifier of the product to add to the subscription.
`Quantity`	`int`	`1`	Number of units of the product to add.
`AlignToCurrentInterval`	`bool`	`true`	Calculates the prorated price so the new product is aligned with the current billing interval.
`GetCustomerPricePreviewOnly`	`bool`	`true`	Returns a price preview without updating the subscription.
`GenerateMail`	`bool`	`false`	Prevents Cleverbridge from sending a confirmation email because the request is for preview only.

Request

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/addsubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": true,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": true
    },
    "GenerateMail": false,
    "ProductId": 123456,
    "Quantity": 1,
    "SubscriptionId": "S12345678"
  }'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "AlignmentSettings": {
    "AlignToCurrentInterval": True,
    "ExtendInterval": False,
    "GetCustomerPricePreviewOnly": True
  },
  "GenerateMail": False,
  "ProductId": 123456,
  "Quantity": 1,
  "SubscriptionId": "S12345678"
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/addsubscriptionitem", 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/addsubscriptionitem',
  '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({
  "AlignmentSettings": {
    "AlignToCurrentInterval": true,
    "ExtendInterval": false,
    "GetCustomerPricePreviewOnly": true
  },
  "GenerateMail": false,
  "ProductId": 123456,
  "Quantity": 1,
  "SubscriptionId": "S12345678"
});

req.write(postData);

req.end();

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

📘
Note
Add a short explanation after the request sample identifying the relevant price fields in the API response and stating whether the displayed amount includes applicable tax.

For more information about the AlignmentSettings argument, see Alignment Settings.

Step 2: Process prorated price

After the customer confirms the previewed price, submit the request again with GetCustomerPricePreviewOnly set to false. This request adds the product to the subscription and processes the applicable prorated charge.

Call the Add Subscription Item API endpoint again. Cleverbridge will process the add-on using the payment details that we have stored in our database and send a confirmation email to the customer.

Parameters

Parameter	Value	Description
`AlignmentSettings.GetCustomerPricePreviewOnly`	`false`	Processes the add-on instead of returning a preview.
`GenerateMail`	`true`	Sends the customer a confirmation email after the subscription is updated.

Request

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/addsubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": true,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "GenerateMail": true,
    "ProductId": 123456,
    "Quantity": 1,
    "SubscriptionId": "S12345678"
  }'

Step 3: Receive the PaidOrderNotification

Cleverbridge sends a PaidOrderNotification after the payment is received. Use the subscription and order information in the notification to update connected systems such as your CRM, ERP, or entitlement platform.

The purchase status fields can be used to determine whether the order is paid.

PaidOrderNotification Parameters

Parameter	Definition
`subscriptionId`	Unique ID of the Cleverbridge subscription.
`intervalNumber`	Number of the billing interval associated with the subscription item.
`nextBillingDate`	Date on which the subscription is currently scheduled to renew. When the add-on is aligned to the current interval, it follows the existing renewal schedule.

{
  "meta": {
    "type": "PaidOrderNotification",
    "date": "2019-03-19T14:47:34.857671",
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"
  },
  "purchaseId": 123456789,
  ...
  "items": [{
    ...
    "recurringBilling": {
      "subscriptionId": "S12345678",
      ...
      "intervalNumber": 1,
      ...
      "nextBillingDate": "2020-01-01T12:59:59.111100",
      ...
    }],				
  ...
  }
}