Overview

This guide shows you how to apply a one-time discount to a customer's next billing interval using the Update Subscription Item endpoint.

Use Case

Cloudify identifies a customer as a churn risk and wants to offer a discount to keep them subscribed.

Cloudify creates an item-level promotion in Subscription Commerce Manager (SCM) with a one-time coupon code.
The customer agrees to accept the discount in exchange for staying subscribed.
Cloudify's system calls the Update Subscription Item endpoint with the coupon code and sets the change to apply at the next renewal.
Cleverbridge emails the customer to confirm the update.

Result

The customer's subscription renews at the discounted price for one billing interval, and the customer remains subscribed.

Diagram

Implement the Update Subscription Item endpoint

Before you start

Make sure you have:

An active subscription with at least one subscription item.
An item-level promotion in Subscription Commerce Manager (SCM) configured to apply to one subscription billing interval only.
A coupon code generated for that promotion.
The customer's explicit consent to apply the discount.

🚧
Important
This discount also applies to other events that happen before the renewal, such as product upgrades or added licenses.
Be aware of this limitation when using the API.

In the API call:

Set GenerateMail to true so that the customer receives a confirmation email that the discount was applied.
Set all parameters in the AlignmentSettings argument to false so that the change is applied to the next billing interval.

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

Parameters

Parameter	Type	Required by API	Example	Notes
`SubscriptionId`	string	Yes	`S67439867`	Identifies the subscription that owns the item.
`RunningNumber`	integer	Yes	`1`	Identifies the specific subscription item within the subscription.
`ProductId`	integer	Yes	`292122`	The product associated with the subscription item.
`Quantity`	integer	Yes	`1`	The quantity of the subscription item. Send the current quantity if you aren't changing it.
`CouponCode`	string	No	`YOUR_COUPON_CODE`	Optional in the API; required for this workflow.
`UpdateAction`	string	Yes	`Update`	The type of update being performed. Use `Update` when modifying an existing item.
`GenerateMail`	boolean	No	`true`	Optional in the API and defaults to `true`. Keep it `true` for this workflow so the customer receives a confirmation email.
`TriggerImmediateRenewal`	boolean	No	`false`	Optional in the API and defaults to `false`. Keep it `false` to apply the discount at the next renewal.
`AlignmentSettings`	object	No	see below	Optional object in the API; used here to apply the discount at the next renewal.
`AlignmentSettings.AlignToCurrentInterval`	boolean	Yes	`false`	Applies the change to the current interval when `true`. Set to `false` for a next-interval discount.
`AlignmentSettings.ExtendInterval`	boolean	No	`false`	Optional. Extends the current billing interval when `true`.
`AlignmentSettings.GetCustomerPricePreviewOnly`	boolean	Yes	`false`	Returns a price preview without saving changes when `true`. Set to `false` to commit the update.

Request

curl --location 'https://rest.cleverbridge.com/subscription/updatesubscriptionitem' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS' \
--data '{
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "ExtendInterval": false,
    "GetCustomerPricePreviewOnly": false
  },
  "CouponCode": "YOUR_COUPON_CODE",
  "GenerateMail": true,
  "ProductId": 292122,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67439867",
  "TriggerImmediateRenewal": false,
  "UpdateAction": "Update"
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "AlignmentSettings": {
    "AlignToCurrentInterval": False,
    "ExtendInterval": False,
    "GetCustomerPricePreviewOnly": False
  },
  "CouponCode": "YOUR_COUPON_CODE",
  "GenerateMail": True,
  "ProductId": 292122,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67439867",
  "TriggerImmediateRenewal": False,
  "UpdateAction": "Update"
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/updatesubscriptionitem", payload, headers)
res = conn.getresponse()
print(res.read().decode("utf-8"))

async function main() {
  const response = await fetch('https://rest.cleverbridge.com/subscription/updatesubscriptionitem', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
    },
    body: JSON.stringify({
      AlignmentSettings: {
        AlignToCurrentInterval: false,
        ExtendInterval: false,
        GetCustomerPricePreviewOnly: false
      },
      CouponCode: 'YOUR_COUPON_CODE',
      GenerateMail: true,
      ProductId: 292122,
      Quantity: 1,
      RunningNumber: 1,
      SubscriptionId: 'S67439867',
      TriggerImmediateRenewal: false,
      UpdateAction: 'Update'
    })
  });

  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 = "{"
        + "\"AlignmentSettings\":{"
        + "\"AlignToCurrentInterval\":false,"
        + "\"ExtendInterval\":false,"
        + "\"GetCustomerPricePreviewOnly\":false"
        + "},"
        + "\"CouponCode\":\"YOUR_COUPON_CODE\","
        + "\"GenerateMail\":true,"
        + "\"ProductId\":292122,"
        + "\"Quantity\":1,"
        + "\"RunningNumber\":1,"
        + "\"SubscriptionId\":\"S67439867\","
        + "\"TriggerImmediateRenewal\":false,"
        + "\"UpdateAction\":\"Update\""
        + "}";

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://rest.cleverbridge.com/subscription/updatesubscriptionitem"))
        .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

{
  "AlignmentCustomerGrossPrice": 120.00,
  "AlignmentCustomerNetPrice": 100.00,
  "AlignmentCustomerVatPrice": 20.00,
  "NextBillingCustomerGrossPrice": 108.00,
  "NextBillingCustomerNetPrice": 90.00,
  "NextBillingCustomerVatPrice": 18.00,
  "NextRenewalCustomerGrossPrice": 96.00,
  "NextRenewalCustomerNetPrice": 80.00,
  "NextRenewalCustomerVatPrice": 16.00,
  "PriceCurrencyId": "USD",
  "ResultMessage": "OK"
}