Usage Buckets

Last Updated: Thu Nov 23 2023

Bucketing is configured in Setup / Usage Rating / Bucket & Share Plans

An allocation bucket represents a data aggregator. The motivation of a bucket is best explained by providing an example. It is quite common for businesses to provide a free usage allowance as part of their offering; e.g. a customer signing up for Plan A pays $5 monthly and gets 10MB of data each month. Any data consumed above and beyond 10MB is subject to overage charges at a rate of $1 for each MB. In order to configure this, the administrator would create a service and attach it to a package having a monthly plan with a $5 charge for that service.

The 10MB usage allotment is handled by configuring a monthly recurring data bucket with a value of 10 MB and attaching it to that service. At the start of the period, the bucket is replenished with 10 MB. As data arrives in the system, the rating engine will apply the applicable usage from the 10MB bucket until the 10MB is used up. When the bucket is depleted, the system will then rate all data according to the rate plan configuration.

Base Buckets

A base bucket represents a definition of an allocation bucket. It is a template for creating usage buckets and defines the data type of the bucket. Several types are supported:

Unit Type



Time buckets are buckets that aggregate usage based on a time measurement (e.g. length of a phone call, time spent streaming media etc.). A bucket offering 1000 min of monthly calling is an example of a time bucket.


Data buckets aggregate usage based on how many bytes (KB, MB, GB etc.) was used up. As an example a buckets offering 10MB of usage is a data bucket.


Count buckets are buckets that aggregate based on number of times a given event occurred – e.g. number of API calls

Usage Buckets

Usage buckets are what are applied to packages and services. Base buckets represent a template type for a bucket created. A usage bucket defines attributes such as recurrence type and frequency, proration and volume tiers (single or multiple). Three recurrence types are supported:




A non-recurring bucket is a one-time bucket that is applied to a service. Once the usage has been applied, the bucket allotment is over and cannot be reused. Expiry dates can be set on non-recurring buckets to ensure that usage has an end date. Examples of this could be a promotional one time add on of usage for a service.


A recurring bucket refills itself each period. A period could be a month or a year. Any unused amount at period end is forfeited and a new allocation of usage is provided the following period.

Recurring with rollover

A recurring with rollover bucket is similar to a recurring bucket except that any unused bucket allocation at period end is now added to next months’ allotment. For instance, if a 10 MB recurring with rollover bucket was configured and 8 MB was used up, the 2MB remainder is now added to the new 10 MB allotment in the subsequent period. This means that the customer now gets 12 MB of usage for the new period.

Rate Plans

An allocation bucket can be associated with a rate plan. The rate plan defines the charges that are applied for the usage being aggregated. Conditional rates can be applied to buckets. When a bucket is applied to the account, the rating engine will apply the rates associated with the bucket first.

Once the bucket allotment has been used up, the rating engine will then apply the rates associated with the underlying service. The order of precedence is as follows (highest to lowest priority): bucket rate plan, service rate plan, package rate plan, account rate plan, owner rate plan. A bucket can be configured with a free rate plan to satisfy scenarios where the service provider wishes to offer plans with a free included usage allotment.

Bucket Priorities

Multiple usage buckets can be applied to an account. When bucketing, the system will first check to see if an account service level bucket is defined. If so, it will apply usage against that bucket. If multiple buckets are configured, the bucket with the most immediate expiry date will be used up first. If buckets have the same expiry date, then the non-recurring buckets will be chosen first, followed by the recurring with rollover bucket followed by the recurring bucket. Once the account service buckets are depleted, usage will be applied against the account bucket. After the account bucket is depleted, usage will be applied against the parent account level bucket.

Tiered Buckets

Buckets can be tiered to support multiple levels of charges based on thresholds. An administrator may wish to support a certain set of rates for the first tier, with a different set of rates when the user has exceeded the first tier of usage in that period.

Threshold notifications can also be configured for each tier to inform the user of the system when a tier is has expired. The system allows the administrator to configure as many tiers and threshold notifications as required.

In multi-tiered scenarios, the business can specify if the last tier is an uncapped tier which implies that there is no upper limit to the amount of usage that is used up for that tier. It is also possible to set a flat charge when transitioning between tiers; e.g. once a 1 MB threshold has been reached, the user now pays a $5 flat charge to enter tier 2.