Overview

This guide shows you how to implement the Update Subscription Item Price API endpoint to use a tiered or volume pricing approach to bill a customer for usage.

Use Case

On October 17, a customer subscribes to Cloudify Messaging, a usage-based service billed at the end of each monthly billing period based on how many messages are sent. Cloudify charges per message using these pricing tiers:

Messages per month	Price per message - Billed monthly
1,000 or fewer	$5.00
1,001–10,000	$1.00
10,001–50,000	$0.75
50,001–100,000	$0.50
Over 100,000	$0.30

The customer enters payment details at checkout, but no charge is created on October 17.
At the end of the billing period (November 16), Cloudify’s system does the following for subscriptions renewing on November 17:

Calculates how many messages the customer sent during the month
Determines the correct tier price
Uses the Update Subscription Item Price endpoint to update the subscription item’s quantity and price

On November 17, Cleverbridge automatically bills the customer $39,211 for 78,421 messages, priced at $0.50 per message.

Implement Update Subscription Item Price API endpoint

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the messages item is the only item in the subscription).
`Quantity`	78,421
`AlignmentSettings`	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`
`CustomerPrice`	`CurrencyId: JPY` `IsGross: false` `Value: 0.50`
`UpdateAction`	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)

Diagram

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

  A(["&nbsp;&nbsp;<br/><b>October 17</b><br/>The customer enters payment details at checkout,<br/>but no charge is created&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/><b>November 16</b><br/><i>Update Subscription Item Price</i> calculates how many messages<br/>the customer sent during the month and updates the price according to tier&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>November 17</b><br/>Cleverbridge automatically bills the customer&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor