Overview

This guide shows you how to implement the Update Subscription Item API endpoint twice to co-term subscription items by shortening the billing interval of the additional seat.

Use case

A customer signs up for your Cloud Storage service and receives one seat for $1200.0 per year.
The customer receives an offer for an additional seat that can be purchased at a discounted price - $600.00 for a one-year seat - if the customer purchases the seat immediately.
On your Customer Self-Service page: The page uses the Update Subscription Item API endpoint to obtain and display the price of the pro-rated additional seat that will terminate in 6 months. The next billing date for both seats is also shown.

Result

On the 13th November, the customer is charged $900 to renew the seats

$600.00 for the original seat
$300.00 for the additional seat

Timeline

Implement the API endpoints

Call the Update Subscription Item API endpoint twice

Before you start

Make sure that:

The subscription has the status Active.

🚧
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.

Step 1: Preview of price and next billing date

If the API call is formatted as described below, it will:

Calculate price if the new purchase and renewal are made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	AlignToCurrentInterval: true GetCustomerPricePreviewOnly: true ExtendInterval:false	The subscription is changed as requested in the API call.
GenerateMail	bool	No	false
ProductId	int	Yes	294835	Product ID for the subscription item usage.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	2	Total number of items after the update.
SubscriptionId	str	Yes	S68841753	The unique identifier of the subscription.
UpdateAction	str	No	0	The value set does not affect transaction processing. See the note below.

JSON Body

{
    "ProductId": 294835,
    "RunningNumber": 1,
    "SubscriptionId": "S68841753",
    "UpdateAction": 0,
    "Quantity": 2,
    "GenerateMail": false,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": true,
        "ExtendInterval": false
    }
}

Request

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YW5uYS5rdWxjenlja2E6QExvZWJhdWVyMjAyNg==' \
--header 'Cookie: __cf_bm=A6K7aOZPXG0HMQLsx4EJ2WmkiJ3EP_aKdj9e1HjGFzM-1778670865.9642408-1.0.1.1-VmH0AcB2VTWj9lduFwRXCBfuY6xwPxhyYNoHiFbOmnutisYTNLXHEv1FrqPf316uqjIp6WoxhtfL8va1qxWhH_AtmVPUK_uZHHsqdtuCSobPoxkvHXUnkvT0GqgcXKD1; __cflb=0H28uwNFGpYQrCsehBGT3RYaSUCcWKg6WyaLHLyGFg9' \
--data '{
    "ProductId": 294835,
    "RunningNumber": 1,
    "SubscriptionId": "S68841753",
    "UpdateAction": 0,
    "Quantity": 2,
    "GenerateMail": false,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": true,
        "ExtendInterval": false
    }
}'

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YW5uYS5rdWxjenlja2E6QExvZWJhdWVyMjAyNg==' \
--header 'Cookie: __cf_bm=A6K7aOZPXG0HMQLsx4EJ2WmkiJ3EP_aKdj9e1HjGFzM-1778670865.9642408-1.0.1.1-VmH0AcB2VTWj9lduFwRXCBfuY6xwPxhyYNoHiFbOmnutisYTNLXHEv1FrqPf316uqjIp6WoxhtfL8va1qxWhH_AtmVPUK_uZHHsqdtuCSobPoxkvHXUnkvT0GqgcXKD1; __cflb=0H28uwNFGpYQrCsehBGT3RYaSUCcWKg6WyaLHLyGFg9' \
--data '{
    "ProductId": 294835,
    "RunningNumber": 1,
    "SubscriptionId": "S68841753",
    "UpdateAction": 0,
    "Quantity": 2,
    "GenerateMail": false,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "GetCustomerPricePreviewOnly": true,
        "ExtendInterval": false
    }
}'

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YW5uYS5rdWxjenlja2E6QExvZWJhdWVyMjAyNg==',
    'Cookie': '__cf_bm=A6K7aOZPXG0HMQLsx4EJ2WmkiJ3EP_aKdj9e1HjGFzM-1778670865.9642408-1.0.1.1-VmH0AcB2VTWj9lduFwRXCBfuY6xwPxhyYNoHiFbOmnutisYTNLXHEv1FrqPf316uqjIp6WoxhtfL8va1qxWhH_AtmVPUK_uZHHsqdtuCSobPoxkvHXUnkvT0GqgcXKD1; __cflb=0H28uwNFGpYQrCsehBGT3RYaSUCcWKg6WyaLHLyGFg9'
  },
  body: JSON.stringify({
    "ProductId": 294835,
    "RunningNumber": 1,
    "SubscriptionId": "S68841753",
    "UpdateAction": 0,
    "Quantity": 2,
    "GenerateMail": false,
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "GetCustomerPricePreviewOnly": true,
      "ExtendInterval": 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/updatesubscriptionitem")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("Authorization", "Basic YW5uYS5rdWxjenlja2E6QExvZWJhdWVyMjAyNg==")
  .header("Cookie", "__cf_bm=A6K7aOZPXG0HMQLsx4EJ2WmkiJ3EP_aKdj9e1HjGFzM-1778670865.9642408-1.0.1.1-VmH0AcB2VTWj9lduFwRXCBfuY6xwPxhyYNoHiFbOmnutisYTNLXHEv1FrqPf316uqjIp6WoxhtfL8va1qxWhH_AtmVPUK_uZHHsqdtuCSobPoxkvHXUnkvT0GqgcXKD1; __cflb=0H28uwNFGpYQrCsehBGT3RYaSUCcWKg6WyaLHLyGFg9")
  .body("{\n    \"ProductId\": 294835,\n    \"RunningNumber\": 1,\n    \"SubscriptionId\": \"S68841753\",\n    \"UpdateAction\": 0,\n    \"Quantity\": 2,\n    \"GenerateMail\": false,\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": false,\n        \"GetCustomerPricePreviewOnly\": true,\n        \"ExtendInterval\": false\n    }\n}")
  .asString();

Response

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 2400.0,
    "NextBillingCustomerNetPrice": 2016.81,
    "NextBillingCustomerVatPrice": 383.19,
    "NextRenewalCustomerGrossPrice": 2400.0,
    "NextRenewalCustomerNetPrice": 2016.81,
    "NextRenewalCustomerVatPrice": 383.19,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Response 2

JSON Body

{
    "ProductId": 294835,
    "RunningNumber": 1,
    "SubscriptionId": "S68841753",
    "UpdateAction": 0,
    "Quantity": 2,
    "GenerateMail": false,
    "AlignmentSettings": {
        "AlignToCurrentInterval": true,
        "GetCustomerPricePreviewOnly": true,
        "ExtendInterval": false
    }
}

{
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 1200.0,
    "NextBillingCustomerNetPrice": 1008.40,
    "NextBillingCustomerVatPrice": 191.60,
    "NextRenewalCustomerGrossPrice": 1200.0,
    "NextRenewalCustomerNetPrice": 1008.40,
    "NextRenewalCustomerVatPrice": 191.60,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Response 3

JSON Body

Step 2: Add additional seat immediately at a discounted price (second call)

If the API call is formatted as described below, it will update the customer's subscription data in the Cleverbridge platform.

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	Yes	AlignToCurrentInterval: true GetCustomerPricePreviewOnly: false ExtendInterval:false	The subscription is changed as requested in the API call.
GenerateMail	bool	No	true
ProductId	int	Yes	294835	Product ID for the subscription item usage.
RunningNumber	int	Yes	1	Running number of the item in the subscription.
Quantity	int	Yes	2	Total number of items after the update.
SubscriptionId	str	Yes	S68841753	The unique identifier of the subscription.
UpdateAction	str	No	0	The value set does not affect transaction processing. See the note below.

📘
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)

JSON body

Request

Response

Diagram

flowchart LR
  classDef mainColor fill:#ffffff,color:#555555,stroke:#0A73D7,stroke-width:2px;

  A(["&nbsp;&nbsp;<br/><b>Promotional offer sent</b><br/>The customer receives an offer to buy additional seat <br/> at a discounted price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Customer Self-Service</b><br/><i>Update Subscription Item</i> endpoint to obtain and display the price of the additional seat&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>Purchase confirmation</b><br/>The customer clicks <b>Buy now</b>. <br/><i>Update Subscription Item</i> endpoint  used to shorten the billing interval&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor