Overview

This guide shows you how to downgrade a customer's subscription to a cheaper plan using the Update Subscription Item endpoint. Billing occurs when the current billing interval ends.

Use Case

Cloudify wants to let customers on the Cloudify Bronze plan switch to the cheaper Cloudify Iron plan without an immediate charge.

The customer opens the Edit My Subscription page hosted by Cloudify, then selects Cloudify Iron and confirms the downgrade.
Your system calls the Update Subscription Item endpoint with the new ProductId and AlignmentSettings set so the change takes effect on the next billing date, not immediately.
Cleverbridge records the new plan on the subscription. The customer keeps Cloudify Bronze access until the current billing interval ends.

Result

On the next billing date, Cleverbridge bills the customer for Cloudify Iron and sends a confirmation email.

Diagram

Implement Update Subscription Item endpoint

Call this endpoint once, with GetCustomerPricePreviewOnly set to false, to commit the downgrade. Set the AlignmentSettings fields to false so Cleverbridge applies the new plan on the next billing date instead of charging the customer immediately.

Before you start

Make sure that:

The subscription has the status Active
The product you're downgrading to already exists in the Cleverbridge platform
Get the customer's consent before you change their subscription.

🚧
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.
If the customer is in the European Economic Area, Strong Customer Authentication may apply when the price changes. This can affect the renewal success rate.
This call updates the subscription record in the Cleverbridge platform immediately, even though the customer isn't billed until the next billing date.

Step 1: Downgrade plan for customer (effective next billing date)

If the customer would like to downgrade to a cheaper plan, call the Update Subscription Item API endpoint using the ProductId that belongs to the cheaper plan.

Parameters

Parameter	Type	Required	Example	Notes
`SubscriptionId`	string	Yes	`S67204221`	Unique ID of the subscription, with or without the leading `S`.
`RunningNumber`	integer	Yes	`1`	Position of the item within the subscription (e.g., 1 for the first item added).
`ProductId`	integer	Yes	294597	ID of the product the customer is downgrading to.
`Quantity`	integer	Yes	`1`	Total number of items after the update.
`AlignmentSettings`	object	Yes	see below	Controls whether the change bills immediately or on the next billing date.
`AlignmentSettings.AlignToCurrentInterval`	boolean	Yes	`false`	Set to `false` so the new plan doesn't bill until the next billing date.
`AlignmentSettings.ExtendInterval`	boolean	No	`false`	Set to `false` so the current billing interval isn't extended.
`AlignmentSettings.GetCustomerPricePreviewOnly`	boolean	Yes	`false`	Set to `false` to commit the change. Set to `true` to preview pricing without updating the subscription.
`TriggerImmediateRenewal`	boolean	No	`false`	Set to `false` so the downgrade doesn't trigger an immediate renewal.
`GenerateMail`	boolean	No	`true`	Set to `true` so the customer receives a confirmation email about the downgrade.
`UpdateAction`	string	Yes	`Downgrade`	Used for reporting only; it doesn't affect processing.

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 '{
    "SubscriptionId": "S67203942",
    "ProductId": 294581,
    "Quantity": 1,
    "GenerateMail": true,
    "UpdateAction": "Downgrade",
    "RunningNumber": 1,
    "TriggerImmediateRenewal": false,
    "AlignmentSettings": {
        "AlignToCurrentInterval": false,
        "ExtendInterval": false,
        "GetCustomerPricePreviewOnly": false
    }
}'

import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "SubscriptionId": "S67203942",
  "ProductId": 294581,
  "Quantity": 1,
  "GenerateMail": True,
  "UpdateAction": "Downgrade",
  "RunningNumber": 1,
  "TriggerImmediateRenewal": False,
  "AlignmentSettings": {
    "AlignToCurrentInterval": False,
    "ExtendInterval": False,
    "GetCustomerPricePreviewOnly": False
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
}
conn.request("POST", "/subscription/updatesubscriptionitem", 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/updatesubscriptionitem',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic YOUR_BASE64_ENCODED_CREDENTIALS'
  },
  body: JSON.stringify({
    "SubscriptionId": "S67203942",
    "ProductId": 294581,
    "Quantity": 1,
    "GenerateMail": true,
    "UpdateAction": "Downgrade",
    "RunningNumber": 1,
    "TriggerImmediateRenewal": false,
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    }
  })

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"SubscriptionId\": \"S67203942\",\n    \"ProductId\": 294581,\n    \"Quantity\": 1,\n    \"GenerateMail\": true,\n    \"UpdateAction\": \"Downgrade\",\n    \"RunningNumber\": 1,\n    \"TriggerImmediateRenewal\": false,\n    \"AlignmentSettings\": {\n        \"AlignToCurrentInterval\": false,\n        \"ExtendInterval\": false,\n        \"GetCustomerPricePreviewOnly\": false\n    }\n}");
Request request = new Request.Builder()
  .url("https://rest.cleverbridge.com/subscription/updatesubscriptionitem")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Basic YOUR_BASE64_ENCODED_CREDENTIALS")
  .build();
Response response = client.newCall(request).execute();

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

Response

{
    "AlignmentCustomerGrossPrice": 0,
    "AlignmentCustomerNetPrice": 0,
    "AlignmentCustomerVatPrice": 0,
    "NextBillingCustomerGrossPrice": 9.99,
    "NextBillingCustomerNetPrice": 8.39,
    "NextBillingCustomerVatPrice": 1.6,
    "NextRenewalCustomerGrossPrice": 9.99,
    "NextRenewalCustomerNetPrice": 8.39,
    "NextRenewalCustomerVatPrice": 1.6,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Parameter	Notes
`AlignmentCustomerGrossPrice`	Gross amount charged immediately for aligning the subscription, if any. `0` when the change doesn't trigger an immediate charge, as with a downgrade effective on the next billing date.
`AlignmentCustomerNetPrice`	Net amount (before tax) charged immediately for the alignment. `0` under the same conditions as `AlignmentCustomerGrossPrice`.
`AlignmentCustomerVatPrice`	Tax portion of the alignment charge. `0` when no immediate charge applies.
`NextBillingCustomerGrossPrice`	Gross price the customer pays on the next billing date, reflecting the new plan.
`NextBillingCustomerNetPrice`	Net price (before tax) for the next billing date.
`NextBillingCustomerVatPrice`	Tax portion of the next billing charge.
`NextRenewalCustomerGrossPrice`	Gross price for the subsequent renewal after the next billing date. Matches `NextBillingCustomerGrossPrice` unless another change is scheduled between the two dates.
`NextRenewalCustomerNetPrice`	Net price for the subsequent renewal.
`NextRenewalCustomerVatPrice`	Tax portion of the subsequent renewal charge.
`PriceCurrencyId`	Currency of all price fields in the response, as an ISO 4217 code (for example, `USD`).
`ResultMessage`	Status of the request. `OK` confirms the subscription record was updated. This doesn't confirm the customer was billed — billing happens on the next billing date.

Step 2: Cleverbridge processes the downgrade

Cleverbridge processes the downgrade using the payment details stored in Cleverbridge's database.

A confirmation email is sent to the customer.

Step 3: Receive the PaidOrderNotification

Cleverbridge processes the charge asynchronously. After the payment is received, Cleverbridge sends a PaidOrderNotification to your configured notification endpoint.

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 1.
Use the subscription and order information to update connected systems such as your CRM or ERP. 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 subscription item is aligned to the current interval, it follows the existing renewal schedule.

{
  "meta": {
    "type": "PaidOrderNotification"
  },
  "purchaseId": 123456789,
  "items": [
    {
      "recurringBilling": {
        "subscriptionId": "S67204221",
        "intervalNumber": 1,
        "nextBillingDate": "2026-10-09T14:47:34.857671"
      }
    }
  ]
}