Virtual Balances

A virtual balance is a non-G/L balance that is used to track usage for groups and group members that share a group balance. It is created when an aggregated balance is added to a group wallet or group member wallet.

Virtual balances are implemented as postpaid balances, regardless of whether the G/L balance is prepaid or postpaid. As a result, the balance amount starts at zero and increases as usage occurs. This allows subscriber usage to be tracked correctly against the group balance. It also allows a credit limit on a virtual balance to be set as an absolute amount of the group balance credit limit. For example, a group member can be limited to using 500 voice minutes a month.

Virtual balances inherit all settings from the balance template used to create the aggregated G/L balance, including balance type, unit, precision, consumption priority, and validity dates. For example, if the aggregated balance is a simple balance (non-periodic), the virtual balances are also simple balances. If a G/L balance is a periodic balance, all associated virtual balances are periodic, have the same period length, and the same boundaries. For example, if a G/L balance is a daily balance that starts at 5:00 AM and ends 4:59:59 AM the next day, all periods will also start at 5:00 AM and end at 4:59:59 AM. The only setting not inherited from the G/L balance is the credit limit. By default, the credit limit set on virtual balances is infinity, so usage is unlimited. A virtual balance in a subscriber or group wallet does not trigger first-use components in product offers owned by that subscriber or group.

Note: If the virtual balance's associated aggregated G/L balance includes rollover balances, then the rollover balances are available to the virtual balance.

In general, the end times of virtual balances match those of the G/L balance except when the group is in a different time zone than that of the subscriber.

Service providers must use the SubMan API to set the credit limit on a subscriber's virtual balance to limit the usage against the G/L group balance. The credit limit must be set per-balance and can be an absolute value or a percentage of the available credit in the group G/L balance. The available credit is the difference between the credit floor and the credit limit. If the credit limit is defined as a percentage, the virtual balance credit limit adjusts automatically when the group's G/L balance changes. For example, for prepaid G/L balances, a grant to a shared asset that modifies the credit floor automatically increases the percentage-based credit limit.

Balance Instance Creation Policy

When defining a balance template in My MATRIXX, you can specify the balance instance creation policy. This allows you to select whether an instance from the balance template is added to a subscriber or group wallet when an instance already exists in the wallet. This operation occurs when a product offer requiring the balance is included in a catalog item (bundle or product offer) that is purchased:

One per Start Time — If a balance instance exists in the wallet and it has the same start time as the one being added no new instance is added to the wallet. The existing one is used.
One per Wallet — If a balance instance exists in the wallet, it is used regardless of its start time. No new instance is added to the wallet. This method is typically used when you want subscribers to have one balance or meter impacted for all services they own. If you use this balance instance creation policy for a currency balance, you can specify an additional optional main balance property. This setting controls how many real (GL) balance instances are created. The propagation of these real balances to virtual balances both above and below the point of creation uses the following logic:
- For wallets below the Aggregation GL balance in the hierarchy, there is always a virtual balance created in the wallet.
- For wallets above the Aggregation GL balance in the hierarchy, the system determines whether it is an existing aggregation hierarchy to which to connect, or if a new hierarchy needs to be created. This is determined based on the balance TemplateId and StartTime. If both match, the existing hierarchy is used. If the balance TemplateId and StartTime do not match, a new hierarchy is created.
One per Offer Purchase — Always create a new balance instance, regardless of whether an instance already exists. This method always creates a new balance instance for each offer requiring the balance that is associated with the catalog item being purchased. In this method, balances are created on a per-offer basis. For bundles featuring different offers that require the same balance, each associated offer will have its own balance instance.
One per Catalog Item Purchase — Always create one unique balance instance per catalog item purchased. The catalog item has either an offer or bundle template. In this method, balances are created on a per purchase basis. In the case where the catalog item has a bundle template, if the bundle contains offers that require the same balance template, this method creates only one balance instance for those offers.

Virtual Balance Credit Limit

Configure a virtual balance with a credit limit that is a percentage of the threshold limit of the shared group G/L balance. The threshold limit is raised when a shared asset is granted. The threshold limit is lowered when a previously granted asset is forfeited, such as when a recurring grant is canceled or suspended. Lowering the threshold limit of a G/L balance might also lower the thresholds and credit limits of the virtual balance and the balance amount meter.

Notifications and other actions occur only when impacts cause the balance amount to reach some threshold value. Notifications do not occur when the threshold value reaches the balance amount.

For example, suppose a balance or meter amount is at $9, with a threshold that causes a notification to be sent when it reaches $10. If you charged $1, causing the balance or meter amount to rise to the $10 threshold, a notification would be sent, indicating that the balance or meter amount has met the $10 threshold.

If you were to modify the threshold to $9 while holding a balance or meter amount of $9, a notification would not be sent, as the threshold amount will have dipped to the balance or meter amount, and not the reverse.

The threshold might meet the balance or meter amount, without producing a notification, under the following circumstances:

The threshold is changed from $10 to $9 within a pricing configuration, or by a subscriber management request.
The threshold is defined as a percentage of another value, and that value changes, such as the total credit in a shared group G/L balance, or across the underlying balances of a balance amount meter. For example, the threshold might be 10% of what was $100, but has now become $90, having forfeited a recurring grant.