Balance Rollovers

Balance rollover occurs at the end of a period when the unused portion of a prepaid, periodic asset balance, for example, voice minutes or data, is made available for charging usage in subsequent periods. Balance rollovers are handled the same for individual product offers and offers in bundles; all available non-supplemental product offers are evaluated in order of priority until an applicable rollover component is found.

You create balance rollovers in My MATRIXX using rollover components that you then assign to subscription product offers. Because balance rollover is controlled by the pricing a subscription or group owns and is not configured in the balance template, the same balance can be handled differently for different subscriptions and groups. When a balance template is defined to allow rollover, the Rollover Balance Consumption Sequence property specifies the order in which balances are consumed. The valid options are Rollover First and Current Period First. When the rollover balances are to be charged, the rollover balance from the oldest period is used first. For more information about creating balance rollovers, see the discussion about configuring balance template rollover and notifications, and the discussion about creating balance rollovers in My MATRIXX Help.

Note: Rollover components cannot be added to one time, global, or contract product offers. A balance rollover can only be applied to prepaid, periodic asset balances. They cannot be applied to on-demand balances or simple balances.

Each rollover component includes at least one rollover table with rules for selecting a rollover profile. Each rollover profile determines the rollover behavior for a specific balance and includes the following:

Balance template ID for a prepaid, periodic balance — The balance ID specified on the rollover component must match the balance ID specified in the rollover profile.
Start date — Start date for the rollover profile.
Maximum percentage of the unused balance to roll over the first time — The rollover percent (if specified) must be greater than 0 and less than or equal to 100. If the unused balance is rolled over for additional periods, the whole remaining amount is rolled over. For example, if the maximum percentage is 50% and that causes a rollover of 100 megabytes the first period, if that 100 megabytes still exists after the first rollover period and rollover is allowed for at least two periods, the full 100 megabytes is rolled over for the second rollover period (not 50% of 100 megabytes).
Maximum rollover amount — The maximum amount to be rolled over in the initial period. The value must be greater than or equal to zero. If a maximum percentage and a maximum amount are specified, the lesser of the two values is used to determine the rollover amount. Using the example above, if the maximum rollover amount is 50 megabytes, only 50 megabytes is rolled over in the first rollover period, not the 100 megabytes determined by the rollover percentage.
Number of periods the balance can be rolled over — The number of rollover periods must be less than the number of expired intervals in the sliding window for the periodic balance. To roll over balances at the end of a billing cycle, the period type of the periodic balance should be set to billing cycle.
Maximum total amount that can be rolled over from all periods — The maximum combined amount of all rollovers. The value must be greater than or equal to zero.

Note: A rollover profile must include a rollover percent or a maximum rollover amount, or both. The amount to be rolled over can be limited for the first rollover period only.

Revisions made to a rollover profile do not affect previously rolled over balances. Revisions are applied to future rollovers only. For each periodic balance, the set of offers is enumerated in priority (highest to lowest), until a rollover component for the balance is found. This component is then applied to the balance.

Rollover Scenarios describes five rollover scenarios which assume that the rolled over amount is not used throughout the rollover periods (consumption is current period first as defined by the RolloverSequence set when using the SubMan pricing APIs). The grant amount is 500 MB. In the first period (1), the full amount was unused. For each period, the following rules apply:

Max % = 50%
Maximum amount (from the initial period) = 300 MB
Maximum number of periods = 3
Max total amount = 500 MB

Table 1. Rollover Scenarios
Period	Unused Amount + Rollover Amount	Rolled Over Amount
1	500 MB	250 MB 50% of 500 = 250 Note: If a maximum percentage and a maximum amount are specified, the lesser of the two values is used to determine the rollover amount.
2	300 + 250 (period 1)	400 MB 100% of 250 + 50% of 300 (150) = 400
3	100 + 400 (periods 1, 2)	450 MB 100% of 400 + 50% of 100 (50) = 450
4	150 + 450 (periods 1, 2, 3)	275 MB 250 megabytes has expired from the first period. Max Periods = 3 100% of (450 - 250 = 200) + 50% of 150 (75) = 275
5	100 + 275 (periods 2, 3, 4)	175 MB 150 megabytes has expired from the second period. Max Periods = 3 100% of (275 - 150 = 125) + 50% of 100 (50) = 175

Events

When a periodic balance is rolled over, MATRIXX Charging Application generates an MtxBalanceRolloverEvent to record the rollover amount of the balance from the previous period (the period that just ended) and the new end time of all rolled over balances from previous periods.

The MtxBalanceUpdate Flags field value 0x02 indicates that the updated balance is a rollover balance.

If balance forfeiture is enabled, a forfeiture event (MtxForfeitureEvent) is generated when a rollover balance expires and after an optionally configured delay time is forfeited. The Event Detail Records (EDRs) include the forfeited amount of expired rollover balances.

If a charge record includes a balance rollover, the temporary container MtxEventChargeNormalizationInfo includes:

A field indicating if the charge impacts are on a rollover balance.
The update type (rollover to or rollover from).

When SubMan APIs are used to adjust a rollover balance, an MtxRolloverBalanceAdjustEvent EDR is created to record the adjustment. For more information about MtxRolloverBalanceAdjustEvent events, see the discussion about MtxRolloverBalanceAdjustEvent in MATRIXX Integration.

When subscription and event data is exported using the data_export.jar program, the MATRIXX.BALANCE_VALUE table includes a new column, IS_ROLL_OVER, that indicates if a balance value is rolled over from the previous interval. If the balance value is rolled over, the value of the column is true (1). Otherwise, the value of the column is false (0). For more information about exporting subscription and event data, see the discussion about exporting subscription and event data in MATRIXX Integration.

Credit Limits

Balance rollover amounts are not used when calculating credit floors, credit limits, or soft thresholds.

APIs

The following SubMan APIs can be used to adjust a rollover balance:

MtxRequestSubscriberAdjustRolloverBalance
MtxRequestGroupAdjustRolloverBalance

When a SubMan API is used to adjust a rollover balance, an MtxRolloverBalanceAdjustEvent is created to track the rollover. For more information about MtxRolloverBalanceAdjustEvent, see the discussion about MtxRolloverBalanceAdjustEvent fields in MATRIXX Integration.

The MtxResponsePricingBalance returned by the MtxRequestPricingQueryBalance SubMan API includes the field RolloverSequence which is set only if the balance template is configured to allow rollover. When set, the field contains the value of the balance consumption sequence (current period first or rollover balance first). Available rollover balances from prior periods are included in the MtxBalanceInfo.AvailableAmount field in the response. The rollover amount, rollover end time, and remaining rollover counter for each period (interval) are returned in the MtxBalancePeriodInfo. Additionally, in the MtxRequestSubscriberQueryWallet SubMan API response and MtxRequestGroupQueryWallet SubMan API response, the rollover balance amount at the start of the current period is included in the MtxBalancePeriodInfo.RolloverInitAmount field, and the total rollover amount at the start of the current period is included in the MtxBalanceInfoPeriodic.RolloverInitAmountTotal field. For example, Figure 1 illustrates the following scenario:

New plan begins January 1
Monthly grant = 5GB
Data consumable that month
Unused data rolls over for two months
Data is consumed from oldest period first

For more information about the SubMan APIs, see the SubMan API reference MATRIXX Subscriber Management API.