Overview

This guide shows you how to implement Update subscription Item endpoint to change the subscription renewal quantity for a customer.

Use Case

A Cloudify customer’s subscription is automatically renewed on August 15 for €100 for a monthly billing period. The charge consists of:

Base usage: €50
Users: €50 (10 users × €5 per user per month)

The customer plans to add five additional users, effective from the next billing date (September 15).

On September 15, the Cleverbridge platform bills the customer €125 for the monthly renewal, reflecting:

€50 for base usage
€75 for 15 users (15 × €5)

Implement API endpoints

Call the Get Subscription and Update Subscription Item API endpoints as described below.

Before you start

Make sure that:

The subscription has the status Active.
Any changes made, including the price and/or quantity, apply to all future billing events unless modified subsequently.

🚧
Important
Get the customer's consent for changes to subscriptions. 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.

Parameters

Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.
Use the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.

Step 1: Retrieve the Quantity of Users (first call)

To retrieve the current subscription item quantity:

Call the Get Subscription API endpoint.
In the SubscriptionItem array data returned in the response, locate the single instance in the array for which both of the following statements are true:

RunningNumber matches the running number of the subscription item for which the quantity is needed.
The IsCurrent parameter is true.

Retrieve the current quantity for the Users subscription item from this instance of the array.

Step 2: Update Subscription Item Price (second call)

Set the parameters in the Update Subscription Item API call to the values listed in the table.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the free trial product (not product being replaced).
`Quantity`	15 (The new quantity.)
`AlignmentSettings`	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`
`UpdateAction`	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)

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>August 15th</b><br/>Subscription renewed for €100<br/>(€50 base + 10 users × €5 per user per month)&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>The customer adds 5 new users,<br/>effective at the next billing date&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>September 15</b><br/>The customer is billed €125:<br/>€50 for base usage<br/>€75 for 15 users <br/>(15 × €5)&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor