Balance, Meter, and Wallet Management

Thresholds

Balances and meters can have thresholds set on them individually, in addition to any thresholds that were set in the balance template definitions in My MATRIXX. Each threshold is a secondary resource. The number of thresholds (threshold slots) allowed, the threshold IDs, and threshold characteristics, such as whether the threshold is a credit limit, and an absolute value, or a percentage, are statically defined in the balance template definition in My MATRIXX. You can change the value, name and notification status on any unlocked threshold slot and remove any threshold in an unlocked state. Removal of a threshold removes any customized value that were set earlier by using a SubscriberAddThreshold or GroupAddThreshold request. This returns the threshold to its default value, or, in the case of a default credit limit, to the credit limit value set by the pricing administrator. System-level thresholds cannot be removed from a balance.

When you use the AddThreshold or RemoveThreshold SubMan APIs to add, modify, or remove a threshold, an MtxBalanceThresholdModifyEvent EDR is generated if the event is enabled in My MATRIXX. For more information about enabling events, see the discussion about changing an event mapping in My MATRIXX Help.

Adjustments

You can directly update subscription and group balances by topping up or adjusting the balance amount, for example, when a subscription requires additional assets or when a billing complaint is made. A top-up is always a credit on a balance and requires a reference to a voucher that authorizes the top-up. If the top-up is to a periodic balance, only the current period can be topped up. An adjustment type can be a credit (decrease), debit (increase), or reset (meters only). A reset adjustment type makes the current meter amount 0 (zero), resetting the meter count. Adjustments to a balance do not affect any meters that track charges to that balance. To adjust the meter the same amount, you must explicitly adjust the meter in addition to the balance. For all adjustment types, the value is always a positive amount. For adjustments to periodic balances, only the current period can be adjusted. For adjustments and top ups to virtual (aggregate) balances, the amount does not roll up to the group G/L balance.

SubMan APIs

Subscription, group, and wallet queries return an array of all balances in the wallet, including balance thresholds, balance class information, balance amounts, billing cycle information, and VAT information. For queries that include on-demand periodic balances, the periodic balance entry that expires last is returned. Billing cycles are defined as part of pricing configuration and involve defining billing profile templates. For information about defining billing profile templates, see the discussion about billing profile templates in My MATRIXX Help.

Meters are considered a balance type (Category = 3) and are also returned in the response. However, they do not have associated classes, so this information is not returned for meters.

The Start time and end time of impacted periodic balances in SubMan API responses do not take into consideration of balance validity:

• The start time of an impacted periodic balance must be the larger of "balance validity start time" and "period start time."
• The end time of an impacted periodic balance must be the lesser of "balance validity end time" and "period end time."

For example, a periodic balance is valid from Jan. 15 to Dec. 31, and has a new period on the 1st day of every month. If the balance is charged on Jan. 15 (within the first period), then the MtxBalanceUpdate struct in the event for this balance must have BalanceStartTime equal to Jan. 15.

Balance and meter templates, balance and meter classes, and VAT settings for product offers are defined as part of pricing plan creation. For information about creating these items, see My MATRIXX Help.