Overview

This guide shows you how to implement the Get Subscription and the Update Subscription Item Price API endpoints to customize subscription renewal price.

Use Case

A Cloudify customer wants to buy more seats in the future and asks for a discount.
Cloudify agrees and reduces the price per seat from $5.00 to $4.85.
Cloudify updates the subscription seat price using the Update Subscription Item Price API endpoint.
Cleverbridge automatically renews the subscription and bills the end customer.

Implement API endpoints

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.
Use of the CustomerPrice parameter in the API response is required.
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.

For more information on which API endpoint to use, see Guidelines for When to Use UpdateSubscriptionItem vs. UpdateSubscriptionItemPrice.

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

Step 1: Retrieve the Quantity of Users

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

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the seats item is the only item in the subscription).
`AlignmentSettings`	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`
`CustomerPrice`	`CurrencyId: HUF` `IsGross: true` `Value: 1950.00`
`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/>A Cloudify customer wants to buy more seats<br/>and asks for a discount&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>Cloudify reduces the price per seat<br/>from $5.00 to $4.85&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/>Cleverbridge automatically renews the subscription<br/>and bills the customer&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor