Modifying Balance Validity Periods

Extend or shorten the validity end time (expiration date) of simple and periodic G/L balance instances.

Extending the balance validity period enables the balance quantity to be available for a longer period of time and will reactivate a balance if it has expired. The balance end date extension can be implemented by adding a balance state update component to a product offer, and configuring that update component to select a balance state update profile based on conditions valid during rating. The update profile defines how to extend the balance end date.

Shortening the balance validity period allows the balance quantity to be set before the current end time, up to and including the current time (from now), but not to the past. To shorten the balance end date, set the balance state update component End Time Reduction Policy to Allow Reduction Up To Now, and add that component to the product offer. Configure the component to select a balance state update profile based on conditions valid during rating. The update profile defines how to extend the balance end date.

If the offer identifies a required tier balance, and that tier is specified as the target in a balance state update component, that balance instance is always selected for the balance class or template if one is associated with that offer. If a tier is not specified in a balance state update component, the group at the specified tier is selected and its local wallet is evaluated for possible balance class or template matches.

The validity end time of a balance can change due to any of the following:
  • A balance is topped up using the MtxRequestSubscriberTopupBalance and MtxRequestGroupTopupBalance SubMan APIs.
  • A balance is adjusted using the MtxRequestSubscriberAdjustBalance and MtxRequestGroupAdjustBalance SubMan APIs.
  • A balance state update component is applied either through a purchase or auto-renew.
  • A balance auto expires when it reaches a balance amount of zero.
As a result of any of these actions, an MtxBalanceStateUpdate is added to the Event Detail Record (EDR), which includes the following information:
  • BalanceClassId
  • BalanceTemplateId
  • BalanceResourceId
  • OldBalanceEndTime
  • BalanceEndTime
  • AppliedOfferIndex
  • EndTimeExtensionLimitOffset
  • EndTimeExtensionLimitOffsetUnit

When the validity end time of a tier balance is changed, a secondary event with an instance of MtxBalanceStateUpdate is generated to record the end time extension of the tier balance. For more information about required tier balances, see the discussion about product offer required tier balances.

Both balance state update components and profiles are part of a pricing plan and stored in the pricing database. For information about creating a balance state update component, see the discussion about creating a balance state update component in My MATRIXX Help.