Bill Customer for Excess Usage

You can charge your customers for excess usage (overage). The following contains relevant information about this use case:


  1. On March 17th, a customer purchases a SaaS data storage subscription that consists of two subscription items billed on a recurring basis as follows:
    • Base usage: €50 for up to 500 gigabytes, billed at the start of the monthly billing interval
    • Excess usage: Storage used in excess of 500 gigabytes, billed at €1 per 25 gigabytes used and billed in arrears
  2. The same day, the Cleverbridge platform automatically bills the customer €50 for the base usage subscription item.
  3. At the end of the day on April 16th, the client applies a formula to activity records in its data centers to calculate the quantity of excess usage for each customer.
  4. The same day, you run a program that uses the Update Subscription Item endpoint to update the subscription's usage quantity in the Cleverbridge platform. This program calculates usage for each subscription with a renewal date of April 17th.
  5. On April 17th, the Cleverbridge platform automatically bills the customer €58, which is the sum of €50 for base usage and €8 for 200 gigabytes in excess.

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

ParameterSet to Value
SubscriptionIdThe unique identifier of the subscription.
RunningNumber2 (Excess usage is the second of the two subscription items.)
ProductIdProduct ID for the subscription item usage.
QuantityQuantity of excess usage.
AlignmentSettingsAlignToCurrentInterval: false

GetCustomerPricePreviewOnly: false
UpdateActionSee the note below



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)


Although not utilized in this use case, the following options are also available:

  • Reduce the price of the excess usage subscription item by applying a discount coupon that was set up in the Cleverbridge platform.
  • Suppress generation of the confirmation email to the customer for the transaction.



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