Bill Usage using Quantity-Based Pricing
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 17th, a customer subscribes to a cloud messaging product that is billed at the end of every monthly billing interval based solely upon the number of messages sent during that billing interval. The customer was advised that usage during every billing interval would be priced according to the following tiers:
| Number of Messages | Price per Message |
|---|---|
| 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 |
Although the customer was required to enter payment information to complete the purchase, the customer is not billed at this time.
- At the end of the day on November 16th, the program running on your organization’s system does the following for each subscription with a renewal date of November 17th:
- Calculates the quantity of usage during the billing interval, and then uses the same table to determine the correct price at which to bill the usage quantity
- Uses the Update Subscription Item Price endpoint to update the subscription item’s quantity and price
- On November 17th, the Cleverbridge platform automatically bills the customer ¥39,211 (78,421 messages sent, priced at ¥0.50 per message) during the billing interval that ended on November 16th.
Implement Update Subscription Item Price API 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.
ImportantGet the customer's consent for changes to subscriptions. For more information, see Best Practices: Obtain Customer Consent.
Parameters
Parameter | Set to Value |
|---|---|
| The unique identifier of the subscription. |
| 1 (it is assumed that the messages item is the only item in the subscription). |
| 78,421 |
|
|
|
|
| See the note below. |
- Use of the
CustomerPriceparameter 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
AlignmentSettingsparameter for the subscription in the API response is required. Before doing so, see Get Started with Subscriptions > Alignment Settings.
NoteThe
UpdateActionparameter 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)
Illustration
Updated 3 days ago