Overview

This guide shows you how to implement Update Subscription Item endpoint to do charge your customers for excess usage (overage).

Use case

On March 17th, a Cloudify customer buys a subscription containing two subscription items billed on a recurring basis as shown in this breakdown:

To calculate excess usage, the Update Subscription Item endpoint is used.
On April 17th, the customer is billed €58: the sum of €50 for base usage and €8 for 200 gigabytes in excess.

Implement Update Subscription Item Endpoint

Before you start

Make sure that:

The subscription has the status Active.
You know the next reminder date for the subscription because the subscription must be updated with the usage information before this date. The new purchase is created in the Cleverbridge platform on the next reminder date. In order to be billed, the usage information must have been applied to the subscription record in the Cleverbridge system.

🚧
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

This use case calls the Update Subscription Item API endpoint as described below:

Parameter	Type	Required	Example	Notes
AlignmentSettings	obj	No	`AlignToCurrentInterval: false GetCustomerPricePreviewOnly: false`	The subscription is changed as requested in the API call.
ProductId	int	Yes	29899	Product ID for the subscription item usage.
RunningNumber	int	Yes	2	Excess usage is the second of the two subscription items
Quantity	int	Yes	1	Quantity of excess usage
SubscriptionId	str	Yes	S12345678	The unique identifier of the subscription.
UpdateAction	str	No	upgrade	The value set does not affect transaction processing. See the note below.

Use of the CustomerPrice parameter in the API response is optional if you're using the Update Subscription Item API endpoint and required if you're using the Update Subscription Item Price endpoint. Before doing so, see Get Started with Subscriptions > Understand Customer Price.
Use the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscriptions > Alignment Settings.

📘
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)

📘
Note
The Cleverbridge platform generates an email for new purchases that cannot be suppressed.

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>17th March</b><br/>Customer buys a subscription containing two subscription items&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>To calculate excess usage,<br/><i>Update Subscription Item</i> endpoint is used&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>17th April</b><br/>Customer is billed €58:<br/>€50 for base usage + €8 for excess 200 gigabytes&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor