Guides
GuidesAPI ReferenceNotificationsDiscussionsSupportStatus
Start typing to search…

Bill Customer for Excess Usage

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

Implement Update Subscription Item Endpoint

Before you start

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

Important

Get the customer's consent for changes to subscriptions. For more information, see Best Practices: Obtain Customer Consent.


Parameters

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

Parameter

Set to Value

SubscriptionId

The unique identifier of the subscription.

RunningNumber

2 (Excess usage is the second of the two subscription items.)

ProductId

Product ID for the subscription item usage.

Quantity

Quantity of excess usage.

AlignmentSettings

AlignToCurrentInterval: false

GetCustomerPricePreviewOnly: false

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)

Options

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

Note

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

Illustration

Updated about 10 hours ago