Balance Threshold-Based Pricing

You can grant to a balance when subscribers or groups reach a balance or meter threshold (balance threshold-based pricing).

Balance threshold-based pricing is pricing that is applied when a balance or meter threshold is reached in the increasing direction due to a net charge to trigger a balance threshold component. Balance threshold-based pricing can be applied to offer owner state update, grant, and balance state update pricing components.

To trigger grants when balance or meter thresholds are reached, you configure them to have a balance_threshold application type. With this application type set on the grants, when the thresholds are reached, the grants are triggered and the balances specified in the grants are impacted. If the balances specified in the grants are expired when the threshold is reached, the validity of the expired balances must be extended. To achieve this, you configure the balance_threshold application type on balance state update components to trigger based on the same balance or meter threshold.

Balance threshold-based pricing can be applied during usage rating (including first usage rating) or non-usage rating, such as recurring, purchase, cancel, balance adjustment, and balance top-up operations. When the threshold is reached, all grants that have the configuration are triggered. MATRIXX Engine determines which offers to apply the triggered components (offer owner state update, grants, and balance state update components) to as follows:

  • For usage rating:
    • If the balance reaching the threshold is owned by a subscriber, components in the subscriber-owned offers are applied. Additionally, components owned by the device associated with the usage, satisfying the criteria, are also applied.
    • If the balance reaching the threshold is owned by a group, components in the group-owned offers are applied.
  • For non-usage rating:
    • If a subscriber-owned balance that is not specific to a device reaches the threshold, components in the subscriber-owned offers are applied. Additionally, components in all the device-owned offers associated with the subscriber are applied.
    • If the balance reaching the threshold is subscriber-owned and device-specific, components in the subscriber-owned offers are applied with components in the offers owned by the affected device.
    • If a group-owned balance reaches the threshold, components in the group-owned offers are applied.

For usage events, the triggered grants are available for usage charging after the threshold is reached. For other events, the grants are not used to pay any charges incurred in the same operation.

For a multi-SubMan request, the grants from one request are available for subsequent requests.

Balance Threshold Pricing Configuration Fields describes the attributes set on a price component with a balance threshold-based pricing configuration.

Table 1. Balance Threshold Pricing Configuration Fields
Field Name Description
Application The application type of the price component. This indicates that the price component applies to balance threshold-based pricing only.

The value is balance_threshold.

ComponentType The price component to which the balance threshold-based pricing configuration is applied (offer owner state update, balance state update, or grant component).

The value is offer_owner_state, balance_state, or grant.

BalanceId The template ID of the meter or balance.
ThresholdId The ID of the meter or balance threshold, that, when reached, triggers the grant.
Note: Credit-limit thresholds and balance-floor thresholds cannot be used in balance threshold pricing components.
IsInstanceSpecific Flag to indicate if the balance threshold-based pricing configuration is for a specific instance of the balance or for all balances in the template. If true and the triggering balance instance is of the same balance template as specified in any of the applied offer required balances, but this balance instance was not created by this offer during purchase, then this balance_threshold component is skipped. Otherwise, the balance_threshold component is triggered.
RateArray The array that holds the rate tables for the price component.

You set the attributes on the components when you create the components in My MATRIXX. For more information about creating offer owner state, grant, and balance state update components, see the discussions about creating an offer owner state update component, creating a grant, and creating a balance state update component in My MATRIXX Help.

Note the following points about balance threshold-based pricing:

  • Balance threshold-based pricing applies to grants (not charges or discounts).
  • Balance threshold-based pricing does not apply to virtual balances. If the balance reaching the threshold is a virtual balance, then no threshold-based grants or balance state components are triggered.
  • The price components (grant or balance state update) are triggered only when reaching the threshold in the increasing direction (when the balance is raised above the threshold).
  • An application type of balance_threshold is valid only when the referenced balance exists in pricing.
  • When balance threshold-based pricing is configured, each time the balance threshold is reached, an MtxBalanceThresholdEvent Event Detail Record (EDR) can be generated. If a single event (an event that causes the threshold to be reached) causes multiple thresholds on a balance to be reached, or reaches a recurring threshold multiple times, then the pricing is applied and the MtxBalanceThresholdEvent EDR is generated for each threshold reached. For more information, see the discussion about balance threshold-based pricing events.

Balance Threshold-Based Pricing in Offers and Bundles

Grant and balance state update components that trigger on thresholds are configured as a part of an offer. If the offer is a part of a bundle, the components can be overridden or supplemented at the bundle level.

Global offers can also contain components that trigger on thresholds. When used in global offers, the components pnly affect the subscribers and groups that have the threshold referenced.

Example Scenario - Balance Threshold-Based Pricing

An operator wants to grant 100 MB of bonus data to subscribers every time they consume 1 GB of data.

  • The operator sets a meter to analyze user consumption (volume, duration, amount).
  • The operator defines a 1 GB recurring threshold (volume, duration, amount) on the meter.
  • To link the threshold to the grant that applies the 100 MB of bonus data, the operator configures the grant to have an application type of balance_threshold, triggering on the recurring threshold of the usage meter.

Balance Threshold-Based Pricing Events

When balance threshold-based pricing is configured, each time the balance threshold is reached, an MtxBalanceThresholdEvent EDR can be generated (event of type balance_threshold extending from MtxEvent and MtxPrimaryEvent).

The generation of the EDR can be turned on by enabling two flags, one at the global level and one at the threshold level. Both are disabled by default.

If Report Highest Threshold Breaches Only is selected on a balance or meter template, only the highest threshold breach is reported in events.

The engine reports the highest threshold breach on a per-message basis. Therefore, a SubMan multi-request (MtxRequestMulti) might still evoke multiple recorded breaches, but only the highest for each individual component request is reported.

If multiple thresholds are triggered by the same message on the same balance amount, the last processed threshold is the one reported.

For example, if a prepaid balance of -100 units has the following thresholds:
  • A fixed threshold at -50
  • A percentage threshold at 50%
Then usage of 50 units triggers both thresholds, but only the last one processed is reported.

For more information, see the discussions about configuring balance template general properties and configuring meter template general properties in My MATRIXX Help.

If there are any grants triggered by reaching the threshold, the details of the grants (and of any other component applied) are included in the EDR. The base event contains the details of the grants triggered by the threshold.

When enabled, the EDR is generated each time the balance threshold is reached (even if there are no grants triggered by the threshold).

When disabled, the EDR is generated only if there are grants or balance state update components triggered by the threshold (if pricing is applied, the balance threshold EDR is generated regardless of the event enabled flag).

The EDR (with or without the grant details) is separate from the original (usage or non-usage) event that caused the threshold change that triggered the grant(s). For example, if a usage event causes a meter threshold to reach a boundary and trigger a bonus grant, then two EDRs are generated, one for the usage event and one for the threshold that was reached with details of the bonus grant. These EDRs are generated as and when the threshold is reached and are not aggregated (even if the parent usage event is aggregated).

When balance threshold-based pricing is configured, each time the balance threshold is reached, the MtxBalanceThresholdEvent EDR can be generated. If a single event (event that causes the threshold to be reached) causes multiple thresholds on a balance to be reached, or reaches a recurring threshold multiple times, then the pricing is applied and a MtxBalanceThresholdEvent EDR is generated for each threshold reached.

For descriptions of the fields in the balance threshold EDR, see the discussion about MtxBalanceThresholdEvent in MATRIXX Configuration.

Example Use Cases 1 and 2 - Balance Threshold Event Time

The following use cases illustrate how the event time for balance threshold events is set.

Use case 1: For balance threshold events generated when threshold pricing is applied.

  • Case 1a — Threshold pricing is applied directly because of usage rating.
    • For duration (online and offline) — The balance threshold event time is the time at the end of the segment when the threshold is hit. This is the segment start time plus the duration of the segment.
    • For non-duration (online) — The balance threshold event time is the minimum of the segment's time limit and the message event time (min(timeLimit, messageEventTime) ).
    • For non-duration (offline) — The balance threshold event time is the message event time.
  • Case 1b — Threshold pricing is applied because of an ancillary event during usage rating. For example, when a pending recurring event is processed as part of usage, and the recurring charge triggers threshold grants. The balance threshold event time is the event time of the triggering (non-usage) event.

Use Case 2: For balance threshold events generated when an event-enabled flag is set for threshold (no threshold pricing is applied), the balance threshold event time is the message event time.

Balance Threshold-Based Pricing Notifications

Threshold notifications are triggered when the threshold is reached. Optionally, a balance can be configured to trigger the threshold when the balance increases above the threshold value and/or below the threshold value, and can be configured to send a notification when the threshold (soft threshold or credit limit) is reached. For more information, see the discussion about balance template thresholds properties in My MATRIXX Help.

If Report Highest Threshold Breaches Only is selected on a balance or meter template, only the highest threshold breach is reported in notifications.

The engine reports the highest threshold breach on a per-message basis. Therefore, a SubMan multi-request (MtxRequestMulti) might still evoke multiple recorded breaches, but only the highest for each individual component request is reported.

If multiple thresholds are triggered by the same message on the same balance amount, the last processed threshold is the one reported.

For example, if a prepaid balance of -100 units has the following thresholds:
  • A fixed threshold at -50
  • A percentage threshold at 50%
Then usage of 50 units triggers both thresholds, but only the last one processed is reported.

For more information, see the discussions about configuring balance template general properties and configuring meter template general properties in My MATRIXX Help.

Notification Data

When balance threshold-based pricing is configured:

  • If grants are triggered as part of the threshold being reached, the MtxBalanceThresholdNotification includes the details of the grants triggered. These details are stored in the base notification MtxNotification under MtxBalanceImpactInfo.
  • MATRIXX Engine attempts to send a threshold notification every time grants that have a balance threshold-based pricing configuration set on them even if notifications are disabled at the threshold level. Additionally, notification filters are evaluated, which can block the notification from being generated.
  • When an MtxBalanceNotification, for example, an MtxBalanceThresholdNotification, is returned on a purchased item containing a private balance, the notification also includes MtxPurchasedOfferInfo. For more information, see the discussions about MtxBalanceNotification and MtxPurchasedOfferInfo in MATRIXX Integration.