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`	S68912106	Identifier of the existing Cleverbridge subscription to which the product will be added.
`ProductId`	`int`	292973	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 '{
    "SubscriptionId": "S68912106",
    "ProductId": 292973,
    "Quantity": 1,
    "GenerateMail": false,
    "AlignmentSettings": {
      "AlignToCurrentInterval": true,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": true
    }
  }'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S68912106",
  "ProductId": 292973,
  "Quantity": 1,
  "GenerateMail": False,
  "AlignmentSettings": {
    "AlignToCurrentInterval": True,
    "ExtendInterval": False,
    "GetCustomerPricePreviewOnly": True
  }
})
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({
  "SubscriptionId": "S68912106",
  "ProductId": 292973,
  "Quantity": 1,
  "GenerateMail": false,
  "AlignmentSettings": {
    "AlignToCurrentInterval": true,
    "ExtendInterval": false,
    "GetCustomerPricePreviewOnly": true
  }
});

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    \"SubscriptionId\": \"S68912106\",\n    \"ProductId\": 292973,\n    \"Quantity\": 1,\n    \"GenerateMail\": false,\n    \"AlignmentSettings\": {\n      \"AlignToCurrentInterval\": true,\n      \"ExtendInterval\": false,\n      \"GetCustomerPricePreviewOnly\": true\n    }\n  }")
  .asString();

Response

The customer-facing prorated price is AlignmentCustomerGrossPrice. It includes any applicable tax; the tax component is returned separately in AlignmentCustomerVatPrice.

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

{
    "AlignmentCustomerGrossPrice": 4.84,
    "AlignmentCustomerNetPrice": 4.07,
    "AlignmentCustomerVatPrice": 0.77,
    "NextBillingCustomerGrossPrice": 10,
    "NextBillingCustomerNetPrice": 8.4,
    "NextBillingCustomerVatPrice": 1.6,
    "NextRenewalCustomerGrossPrice": 10,
    "NextRenewalCustomerNetPrice": 8.4,
    "NextRenewalCustomerVatPrice": 1.6,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Step 2: Process prorated price

After the customer confirms the previewed price, call the Add Subscription Item endpoint again with the same subscription, product, quantity, and alignment settings used for the preview.

Set GetCustomerPricePreviewOnly to false to add the product to the subscription and process the applicable prorated charge using the customer's stored payment details.
Set GenerateMail to true if Cleverbridge should send a confirmation email to the customer.

Parameters

Parameter	Type	Required	Example	Notes
`GetCustomerPricePreviewOnly`	obj	Yes	false	Processes the add-on instead of returning a preview.
`GenerateMail`	str	Yes	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": 292973,
    "Quantity": 1,
    "SubscriptionId": "S68912106"
  }'

import http.client
import json

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

};
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/addsubscriptionitem")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n    \"SubscriptionId\": \"S68912106\",\n    \"ProductId\": 292973,\n    \"Quantity\": 1,\n    \"GenerateMail\": true,\n    \"AlignmentSettings\": {\n      \"AlignToCurrentInterval\": true,\n      \"ExtendInterval\": false,\n      \"GetCustomerPricePreviewOnly\": false\n    }\n  }")
  .asString();

Step 3: Receive the PaidOrderNotification

Cleverbridge processes the charge initiated in Step 2 asynchronously. After the payment is received, Cleverbridge sends a PaidOrderNotification to your configured notification endpoint.
Do not treat the response to the Add Subscription Item request alone as confirmation that payment was successful.

When you receive the notification:

Verify that meta.type is PaidOrderNotification.
Use purchaseId to identify the paid order and items[].recurringBilling.subscriptionId to correlate it with the subscription updated in Step 2.
Use the subscription and order information to update connected systems such as your CRM, ERP, or entitlement platform and grant or update the applicable entitlement.

Design your notification handler to process retries safely so that receiving the same notification more than once does not create duplicate updates.

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"
      }
    }
  ]
}