Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus

Combine a Usage Data Upgrade with an Early Custom Price Renewal

Overview

This guide shows you how to implement the Update Subscription Item API endpoint to upgrade and renew the customer's subscription immediately.

Use case

  1. The customer reaches the data limit of their current Cloudify plan.

  2. Cloudify offers an upgrade with an early renewal at a custom price, and the customer accepts after reviewing the updated subscription details.

  3. Cloudify uses the Update Subscription Item API endpoint to upgrade and renew the subscription immediately.

    Result:

    The new billing interval starts right away, and the customer regains access on the upgraded plan.

Implement Update Subscription Item

Before you start

🚧

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.

Make sure that:

  • The current billing interval has started and the next billing date has not been reached yet.
  • Any changes made, including the price and/or quantity, apply to all future billing events unless modified later.
  • The renewal is not combined with an alignment of the subscription.
  • The AlignmentSettings parameter for the subscription in the API response is required.
    Before doing so, see Get Started with Subscriptions > Alignment Settings.

Parameters

ParameterTypeRequiredExampleNotes
AlignmentSettingsobjYes{ "AlignToCurrentInterval": false, "GetCustomerPricePreviewOnly": false }The subscription is changed as requested in the API call.
CustomerPriceobjYes{ "CurrencyId": "USD", "IsGross": true, "Value": 70.00 }Pricing information shown to the customer during checkout.
ProductIdintYes293103Product ID of the subscription item.
ResetBillingIntervalboolYestrueSet to true to immediately start the new billing interval. If you use this option, you must also set TriggerImmediateRenewal to true.
RunningNumberintYes1Running number of the item in the subscription.
QuantityintYes1Total number of items after the update.
SubscriptionIdstrYesS67632293The unique identifier of the subscription.
UpdateActionstrNoupgradeThe value set does not affect transaction processing.
See the note below.
TriggerImmediateRenewalboolYestrueTriggers a renewal immediately. As a result, it also extends the next billing cycle by remaining time of current cycle
📘

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)

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 '{
  "ProductId": 293103,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67632293",
  "UpdateAction": "Update",
  "TriggerImmediateRenewal": true,
  "ResetBillingInterval": true,
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": false
  },
  "CustomerPrice": {
    "CurrencyId": "USD",
    "IsGross": true,
    "Value": 70.00
  }
}'
import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "ProductId": 293103,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67632293",
  "UpdateAction": "Update",
  "TriggerImmediateRenewal": true,
  "ResetBillingInterval": true,
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": false
  },
  "CustomerPrice": {
    "CurrencyId": "USD",
    "IsGross": true,
    "Value": 70.00
  }
})
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"))
import http.client
import json

conn = http.client.HTTPSConnection("rest.cleverbridge.com")
payload = json.dumps({
  "ProductId": 293103,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67632293",
  "UpdateAction": "Update",
  "TriggerImmediateRenewal": true,
  "ResetBillingInterval": true,
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": false
  },
  "CustomerPrice": {
    "CurrencyId": "USD",
    "IsGross": true,
    "Value": 70.00
  }
})
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"))
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 YOUR_BASE64_ENCODED_CREDENTIALS")
  .body("{\n  \"ProductId\": 293103,\n  \"Quantity\": 1,\n  \"RunningNumber\": 1,\n  \"SubscriptionId\": \"S67632293\",\n  \"UpdateAction\": \"Update\",\n  \"TriggerImmediateRenewal\": true,\n  \"ResetBillingInterval\": true,\n  \"AlignmentSettings\": {\n    \"AlignToCurrentInterval\": false,\n    \"GetCustomerPricePreviewOnly\": false\n  },\n  \"CustomerPrice\": {\n    \"CurrencyId\": \"USD\",\n    \"IsGross\": true,\n    \"Value\": 70.00\n  }\n}")
  .asString();

JSON body

{
  "ProductId": 293103,
  "Quantity": 1,
  "RunningNumber": 1,
  "SubscriptionId": "S67632293",
  "UpdateAction": "Update",
  "TriggerImmediateRenewal": true,
  "ResetBillingInterval": true,
  "AlignmentSettings": {
    "AlignToCurrentInterval": false,
    "GetCustomerPricePreviewOnly": false
  },
  "CustomerPrice": {
    "CurrencyId": "USD",
    "IsGross": true,
    "Value": 70.00
  }
}

Response

{
    "ContinueUrl": "https://www.cleverbridge.com/864/p/538228779-phYESNsPVfHQ7ZiD4OSI",
    "NextBillingDate": "2026-05-16T08:31:32.834193",
    "NextRenewalDate": "2026-05-16T08:31:32.834193",
    "TransactionStatus": "Success",
    "AlignmentCustomerGrossPrice": 0.0,
    "AlignmentCustomerNetPrice": 0.0,
    "AlignmentCustomerVatPrice": 0.0,
    "NextBillingCustomerGrossPrice": 70.00,
    "NextBillingCustomerNetPrice": 58.82,
    "NextBillingCustomerVatPrice": 11.18,
    "NextRenewalCustomerGrossPrice": 70.00,
    "NextRenewalCustomerNetPrice": 58.82,
    "NextRenewalCustomerVatPrice": 11.18,
    "PriceCurrencyId": "USD",
    "ResultMessage": "OK"
}

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>Data limit reached</b><br/>The customer reaches the data limit&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>Upgrade offered</b><br/>Cloudify offers an upgrade with an early renewal at a custom price&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>New billing starts</b><br/>Cloudify uses the <i>Update Subscription Item</i> API endpoint to upgrade and renew the subscription immediately&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor