Recurring Thresholds

You can define a threshold amount that triggers each time that amount impacts the balance. For example, you can create a recurring threshold that triggers each time a subscriber uses 500 prepaid voice minutes.

If notifications are enabled for a threshold, each time the threshold is triggered, a notification is generated at every recurring value from start to end, inclusive. You can limit the notifications that are triggered by specifying a recurring balance range.

If the threshold is for a prepaid G/L balance, enter negative Start and Stop values. Both values are inclusive, and when the balance amount reaches zero (0), it is handled as a hard credit limit. For example, if a recurring threshold on a prepaid balance has a notification value of 30, a Start value of -20, and a Stop value of -100, the threshold notification will potentially trigger at -20, -50, and -80.

Start — Specifies the starting point from which recurring threshold notifications are triggered:
- prepaid default = infinity (0)
- postpaid default = -infinity (0)
Stop — Specifies the point beyond which recurring threshold notifications are no longer triggered:
- prepaid default = -infinity
- postpaid default = infinity

After a balance instance has been added to a subscriber or group wallet, the recurring thresholds can be set with the following REST APIs:

PUT /v3/subscriber/{ObjectId}/wallet/{ResourceId}/thresholds
PUT /v3/group/{ObjectId}/wallet/{ResourceId}/thresholds

Recurring Threshold Behavior describes how recurring thresholds are defined for prepaid and postpaid balances. Recurring thresholds and a credit limit cannot be set concurrently. In addition, a recurring threshold cannot be set to zero (0), but it can contain decimal values.

Table 1. Recurring Threshold Behavior
Type	Absolute	Percentage
Prepaid	A threshold is triggered at every negative multiple of a specified amount, up to and including the threshold limit. For example, consider the following scenario. Value = -50 Recurring Start = -200 Recurring End = 0 Applies to Increase = true Applies to Decrease = true The threshold is triggered in the following situations. Balance decreases from -200 to -150 Balance decreases from -150 to -100 Balance increases from -100 to -150	A threshold is triggered at every multiple of a specified percentage, up to and including the threshold limit. For example, a threshold can be triggered at multiples of 10 at 10%, 20%, 30% and so forth. A threshold limit must be defined.
Postpaid	A threshold is triggered at every multiple of a specified amount, up to and including the threshold limit. For example, consider the following scenario. Value = 50 Recurring Start = 0 Recurring End = 200 Applies to Increase = true Applies to Decrease = false The threshold is triggered in the following situations. Balance increases from 0 to 50 Balance increases from 50 to 100 No threshold is triggered if the balance decreases from 100 to 50. If no threshold limit is defined, thresholds are triggered for every multiple of 50 with no limit.	A threshold is triggered at every multiple of a specified percentage of the credit floor, up to and including 0%. Credit floors are defined as: Simple Balance — The floor is reset on a grant or top-up to the new balance. For example, if the balance was $5 and there is a $10 top-up, the new floor is $15. Periodic and On-Demand Balances — The floor of each period is the sum of all grants or top-ups into the balance during that period.

For information about setting credit limits and thresholds in a balance template, see the discussion about configuring balance template thresholds in My MATRIXX Help. For information about querying balances and changing thresholds and credit limits, see MATRIXX Subscriber Management API.

Threshold Retriggering

A change to a threshold creates a change to the balance or meter on which it is set. In My MATRIXX, you can define how often you want threshold notifications and events for the same threshold to be triggered during a cycle:

No cycle (default)
Owning balance or meter cycle
Billing cycle

Threshold event and notification retriggering can be independently configured on a per-cycle basis. If you select Unlimited (the default value), notifications and events are triggered each time the threshold is crossed during a cycle. If you select Once Per Cycle, notifications and events are triggered the first time the threshold is crossed during a cycle. Subsequent threshold crossings do not trigger notifications and events. If Once Per Cycle is selected, select the period over which the notification/event is retriggered:

Balance Cycle Aligned — The cycle used for retriggering notifications/events is aligned with the balance cycle.
Note: This option is not available on simple balances.
Billing Cycle Aligned — The cycle used for retriggering notifications/events is aligned with the billing cycle.
No Cycle — The Unlimited or Once Per Cycle selection in Threshold Cycle Notification Limit/Threshold Cycle Event Limit applies over the balance lifetime.

At purchase time, you can override and restore the threshold configuration by extending the SubMan Threshold Add/Remove APIs, for example, MtxRequestSubscriberAddThreshold.

For more information about threshold notification and event options, see the discussions about balance template threshold properties and meter template threshold properties in My MATRIXX Help.

Note: Notification and event history is only recorded when the frequency selection is Once Per Cycle in Threshold Cycle Notification Limit/Threshold Cycle Event Limit. Therefore, if a mid-cycle SubMan API override changes the Unlimited setting to Once Per Cycle, then one further notification/event for the threshold might be generated during the cycle; this is recorded to suppress further notifications and events for that threshold in the cycle.