Balances

Balance properties are defined in templates, and balance templates are derived from a balance class. You define both balance classes and balance templates during pricing plan creation. When you create a new balance, you must define a credit limit threshold for it. Pricing validation requires a credit limit threshold to be defined within the pricing repository for all balances.

Simple Balances and Meters

Simple balances and meters use one balance or meter instance for the entire validity period of the balance or meter. As rating occurs against the instance, the value can increase and decrease according to the applied charges, discounts, or grants.

By default, simple balances and meters are valid immediately and never expire. To limit their availability, you can set effective start and end dates. The end date can be set to indefinite, to a specific date, set after the specified time period relative to the start time or purchase time, or aligned with the end time of the catalog item that creates the balance or meter.

Important: End time alignment to a catalog item is for initialization only. If a balance or meter end time is aligned to a catalog item end time that is modified, an adjustment is required to that balance or meter because balance and meter end times do not track the purchased item cycle, billing cycle, and so on.

When the end date occurs, the instance is no longer valid and cannot be used.

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

Note: Private balance end dates track the purchased item cycle, billing cycle, and so on. This is to maintain the balance if the offer end date is extended and to prevent a private balance from remaining in the database once the owning offer is no longer valid.

For balances, you typically use the effective dates to grant subscribers prepaid assets that expire, but they can also be used for postpaid assets or currencies.

Subscribers and groups can have any number of simple balances in their wallets.

Asset Balances

Assets are financial non-monetary mediums of exchange, such as minutes and megabytes. Both represent a subscriber's liability to a service provider. If Include in Cost is selected in the asset balance, it is reported as a cost balance in SubMan responses and notifications.

Balance Quantities

You can provide subscribers with balance quantities several ways. They can purchase them, receive them as a grant on a recurring cyclical basis, receive them as part of a discount, and earn them based on subscriber-related attributes and balance amounts, such as loyalty points. They can also be provided based on several subscriber management operations such as a balance rollover, a top-up operation, an adjustment, or a transfer.

When first use of a specific balance template causes a grant to that template, the grant is to the balance or period that triggered the grant. Otherwise, when multiple balance instances are in the wallet, a grant is allocated to the balance or period that expires last, so the quantity is available for the longest amount of time.

For information about performing subscriber management operations on balance instances, including balance adjustments, top-ups, transfers, and forfeitures, see MATRIXX Subscriber Management. For information about adjustments to balance amounts, see the discussion about balance and meter adjustments in MATRIXX Pricing and Rating.

SubMan APIs

When an offer is purchased, one or more balance instances are created. The REST APIs return information about balances in the BalanceArray field. Information includes details such as the balance amount, the balance start time and end time, and whether it is a private balance.

Note: The PurchasedItemOwnerResourceId field is only populated for private balances.