Usage Buckets Screen

Last Updated: Thu Nov 23 2023

Usage Buckets are configured in Settings / Usage Rating / Bucket & Share Plans / Usage Buckets


Usage buckets are attached to services in order to provide included usage and usage tiers. Usage buckets utilize base buckets to define basic bucket properties such as the unit of usage deducted from the bucket (data, time etc.), the usage classes that apply to the bucket (data, airtime, events, etc.) and the locations that are applicable to the bucket (Everywhere, North America, etc.). Usage buckets extend the attributes provided by base buckets to create the bucket that is attached to services. With usage buckets you can configure a one-time or recurring bucket, setup usage tiers with flat charges, amongst other options explained further below in this document. Usage buckets can be attached to services in the product catalog, or added as needed to services on accounts.

Money buckets can also be configured which permit one or more types of usage (i.e. time, data, count) to be deducted from a set amount of money configured on the money bucket (e.g. if the bucket is set to $50 then $50 worth of usage can be consumed on the bucket). A money bucket's value will always match the account’s currency that the bucket is configured on. The bucket configuration options that are supported with money buckets are noted below in this document. Money buckets can also be configured on share plans.


  • Base buckets need to be configured before usage buckets can be setup

Buckets Panel

The Buckets panel on the left of this screen allows you to select existing usage buckets to view and edit on the Edit Bucket panel to the right. Actions are also available in this panel which are shown as icons above the Filter text box. The available actions are described below.




Deletes the selected usage bucket if not in use (attached to a service)

Adds a new usage bucket

Edit Bucket Panel

The information in this panel reflects the currently selected usage bucket. From here you can change bucket details (note: fields with a magenta left border are required).

Bucket Fields and Options:

Note: Some of the fields below only appear when configuring certain types of usage buckets (e.g. a recurring bucket or billing activation bucket).

  • Name: a unique name for the bucket

  • Bucket Type: allows you to specify if the bucket is for Usage (a particular class of usage such as ‘data’ can be deducted from the bucket) or Money (multiple classes of usage can be rated and have their rated usage amounts deducted from the amount of money configured on the bucket. E.g. a $100 bucket which can be reduced by data usage, airtime usage, messaging usage, etc.)

  • Convert Data to Binary: When this setting is enabled a data bucket's tier units will be configurable as binary units (kibibytes, mebibytes, etc.). When this setting is disabled a data bucket's tier units will be configurable in decimal units (kilobytes, megabytes, etc.). This setting will be disabled when configuring buckets that do not support data usage (i.e. buckets configured with a Unit Type of ‘Time’ or ‘Count’)

  • Recur Type: determines if the bucket will be replenished or will expire after being used up. The options are:

    • Nonrecurring: used to create a one-time bucket. When the allotted bucket usage is consumed it will not be replenished

    • Recurring: the bucket is reset (replenished) based on the recur frequency specified on the bucket. When the bucket recurs usage will again count against the 1st tier configured on the bucket

    • Recurring with rollover: unused usage will rollover after the bucket recurs. E.g. if a bucket contains 100 GB of usage and 80 GB are consumed at the time of recurrence, the user will have 120 GB of included usage in the bucket. The bucket size is determined by the size of its last tier

  • Expire After: when a nonrecurring bucket should expire. The Expire After field will only appear when selecting the 'Nonrecurring' Recur Type

  • Recur Frequency: how often the bucket will be replenished. Enter a number and unit e.g. to configure a monthly recurring bucket set Recur Frequency to '1' and Unit to 'Month'. This field will only appear if the bucket is configured to recur

  • Expire After Recurrence: allows you to expire the bucket after it recurs a specific number of times. If left empty the bucket will recur indefinitely. This field will only appear if the bucket Recur Type is configured with a recurring option

  • Overage Rate Plan: Allows a rate plan to be added to the usage bucket which will be used to rate usage when the usage provided by the bucket is fully consumed. Overage rate plans can be configured on recurring buckets (with or without rollover) but not on nonrecurring buckets. Overage rate plans are not applicable to activation buckets or share plan add-on buckets. An overage rate plan set on a usage bucket will override rates configured in price plans

  • Billing Activation: this setting will configure the bucket as a billing activation bucket, which can only be added to billing activation services (see the services screen help for more information on billing activation services). When this option is enabled usage threshold and time expiry settings will appear. These activation settings determine when to trigger billing for packages that are configured with a billing activation service. For example, you could configure '1' 'Megabyte' and '1' 'Week' and any package setup with an activation service using the activation bucket would become active when either a megabyte of data is used (combined usage from all of the services in the package) or a week has gone by since the package was added to the account (whichever condition is met first). This option is not available when configuring money buckets

  • Prorate: if enabled this setting will prorate the usage provided in the first tier when a recurring bucket is added to a service on an account. E.g. if a monthly recurring bucket is added in the middle of the month and the account's bill day is set to the 1st of the month, the normal allotment of Tier 1 usage on the bucket will be halved. If this setting is enabled proration will also occur when canceling the service that the bucket resides on, truncating the usage that the bucket provides and potentially pushing the usage that has been accumulated into additional bucket tiers and/or overage. This setting will be disabled when configuring a nonrecurring bucket

Base Buckets tab

Base buckets are used to define the types of usage that can be applied to the usage bucket. E.g. the unit that the bucket uses (Time, Data, Count), usage classes that are applicable to the bucket and other base characteristics. See the base buckets screen help for more information. When configuring usage buckets (usage buckets with a Bucket Type of ‘Usage’) the Unit Type field on the Base Buckets tab will be restricted to one type of usage (only base buckets set with a Unit Type of ‘Time’ for example). Money buckets however, can add base buckets that are configured with different Unit Types (i.e. Data, Count, Time) so that you can deduct any type of usage from the money value configured on the bucket.

Tiers tab

Note: Money buckets do not support bucket tiers. This tab will not appear when configuring a money bucket.

Bucket tiers provide a means of configuring tiers of usage (data, airtime, events, etc.) on a bucket. A flat charge can be applied when entering a tier. A tier with a flat charge of zero will provide free usage when entering the tier or consuming usage while within the tier threshold. The guides section below describes how to configure tiers on a usage bucket.

  • Last Tier Repeats: enabling this option will cause the final tier on the bucket to repeat (including the flat charge) when the final tier threshold is reached. If this option is not selected once the threshold on the last tier is reached the rate to charge will be determined by looking for a configured rate plan (e.g. a rate plan on the account-service, account, etc.). For more information on rate plan selection behavior see the rate plans screen help. This setting will be disabled when configuring a nonrecurring bucket


Note: bucket sizing/amounts can be modified (overridden) on the Package Frequency screen for stand alone buckets and on the Share Plans screen for share plan buckets.

Adding Usage Buckets

  1. Under the Buckets heading on the left click the (emoji) icon

  2. Under the Add Bucket heading on the right specify the bucket details

  3. On the Base Buckets tab:

    1. Select a Unit Type (Time, Data, Count) that will be applicable to the bucket (note: money buckets can use multiple types)

    2. In the Base Bucket field type to search for the base bucket you wish to add and then click to select it when the bucket is listed

    3. Click the +Add button to add the base bucket to the usage bucket

    4. Add additional base buckets if desired

  4. For Usage buckets the Tiers tab will appear after adding a base bucket. On the tab configure the tiers (at least one tier is required):

    1. Enable the Last Tier Repeats option if you wish the bucket to provide usage indefinitely (i.e. you can continue to apply flat charges for the final tier instead of utilizing an overage rate plan when the bucket tiers are exhausted)

    2. Click on the + New button and populate the following fields:

      • Flat Charge: the value entered in this field will be charged when the tier is reached. If a flat charge is configured on the 1st tier then any amount usage applicable to the bucket (e.g. 1 byte of usage against a data usage bucket) will cause the tier to be reached and the flat charge applied

      • Threshold: specifies the size of the tier (the unit options available on this screen are determined by the base bucket's Unit Type). E.g. for a data bucket you would enter a Threshold of '10' with a Unit of 'GB' to create a tier ten Gigabytes in size. Bucket tiers can also be sized with values that result in fractional thresholds (e.g. a bucket tier with a threshold set to 0.1Mib would result in a bucket tier size of 104857.6 bytes). Bucket tiers with fractional byte values will be rounded to whole numbers during rating when usage is applied to the bucket. When a bucket tier threshold is exceeded any flat charge and rates setup on the next tier will be applied. If there is no higher tier to use, and the last tier is not set to repeat, then rates in a rate plan will be used to calculate usage charges (the lowest level rate plan found will be selected if multiple rate plans are available. See the rate plan screen help for details on how rate plans are selected by the system). If no rate plan can be found the rating engine will generate a rating exception when processing non-bucketed usage related to an account-service

  5. Click Add when finished populating tier details. Repeat the process to add additional tiers if desired

  6. When you have finished configuring the usage bucket click Save

Adding Usage Buckets to Services

See the services help guide for instructions on adding usage buckets to services in the product catalog.

Editing Usage Buckets

  1. Under the Buckets heading on the left click the usage bucket you wish to edit

  2. Under the Edit Bucket heading on the right modify the Bucket details

  3. To add or remove base buckets on the usage bucket access the Base Buckets tab and add base buckets as described in the ‘Adding Usage Buckets’ section above. To remove an existing base bucket, click the (emoji) icon next to the bucket and then the (emoji) icon to mark the bucket for deletion. When the bucket changes are saved the base bucket(s) will be deleted from the usage bucket

  4. To edit the Tier configuration on the bucket, load the Tiers tab and click the (emoji) icon next to the tier. Modify the Flat Charge, Threshold and Unit values as desired and then click Update. To remove an existing tier, click the (emoji) icon next to the tier and then the (emoji) icon to mark the tier for deletion (note: once the first tier has been configured and saved on the usage bucket, it cannot be deleted). When the bucket changes are saved the tier(s) will be deleted from the usage bucket

  5. To commit your changes click Save

Deleting Usage Buckets

Note: Usage buckets that are configured on services and other entities are in use and cannot be deleted. In order to delete a usage bucket that is in use, first determine which entities are configured with the bucket and then edit those entities to use an alternate usage bucket.

  1. Under the Buckets heading on the left select the usage bucket you wish to delete

  2. Under the same Buckets heading on the left click the (emoji) icon

  3. On the confirmation dialog that appears select Yes