Private Balances

A private balance restricts balance usage to a specific subscriber, group, or device on a subscription product offer.

A private balance is only available for subscription product offers. One-time offers do not support private balances. Because global offers and contract offers do not support required balances, by default, they do not support private balances.

To set the balance used by each purchased instance to private, select Private Balance on the General tab when creating a balance template. This allows multiple instances of the same product offer to operate independently and concurrently by allowing a balance distribution normalizer to only use the specific balances associated with each purchased instance of the product offer. For more information, see the discussion about configuring balance template general properties in My MATRIXX Help.

For the conditions that must be met to set a balance template as private, see the discussion about private balance validation.

A private balance cannot be modified by the purchase of another offer to top-up the asset of the same balance template.

Set a required balance as private on a subscription product offer revision in My MATRIXX. A private balance is created upon offer or bundle purchase or activation, and is specific to the purchased catalog item. Because the private balance is created at purchase or activation, if the required balance is deleted and then later added back to the offer, the private setting is no longer part of that balance.

A virtual balance is set to private when the aggregating balance is private. The owning offer of the private virtual balance is the owning offer of the private aggregate balance. If an aggregate balance template is marked as private in the product offer’s required balance list, the corresponding virtual balances (including virtual periodic balances) across the group hierarchy are marked as private to the original purchasing owner and offer. When a balance expires, the object is purged from the owner's wallet after a configurable amount of time. When a member of a group purchases an offer with a private aggregate balance, once the balance expires the object is purged from the owner's wallet after a configured amount. The private virtual balance of the group, the members of the group, and groups in a higher tier are also purged.

When a bundle is purchased or activated, any offers that require private balances will create private balances owned by the bundle. If multiple offers within a bundle have the same balance template required as a private balance, the private balances for that single balance template are combined into a single private balance for that bundle, as shown in Figure 1.

A private balance end date (EndTime) can be modified through the MtxRequestSubscriberTopUpBalance SubMan API. A private balance start date (StartTime) cannot be modified.

For more information, see the discussion about MtxRequestSubscriberTopUpBalance in MATRIXX Subscriber Management API.

You can set a simple, prepaid, private balance to expire once the balance is consumed (reaches its credit limit). To set a private balance to expire upon full consumption, select both Is Private and Expire On Consumption in the Required Balances table on the subscription product offer Balances tab. Expire On Consumption is only available when Is Private is selected, and there can be only one expire on consumption balance per catalog item. After the private expire on consumption balance expires, it is removed from the system alongside the owning product offer, catalog item, and owning bundle. Any other private balances connected to this expired offer within the expired catalog item are also expired. Non-private balances are unaffected and are available for offers outside the expired catalog item that refers to these balances. For more information, see the discussion about adding balances in My MATRIXX Help.

When a private balance is set to expire upon consumption, all offers, bundles, and private balances linked to the catalog item that contains a private expire on consumption balance expire upon consumption of that balance. Non-private balances are unaffected and available to the subscriber through offers outside of the expired catalog item. Balances, product offers, catalog items, and bundles are removed after they are no longer required.

When an MtxBalanceNotification, for example, an MtxBalanceThresholdNotification, is returned on a purchased item containing a private balance, the notification also includes MtxPurchasedOfferInfo. For more information, see the discussions about MtxBalanceNotification and MtxPurchasedOfferInfo in MATRIXX Integration.