Eligibility Rules for Catalog Items

Eligibility rules are reusable pricing components that define which offers and bundles are available to subscribers, groups, and devices.

Pricing planners configure eligibility requirements and exclusions in My MATRIXX to specify which subscribers, groups, and devices are eligible to purchase certain catalog items.

Catalog item eligibility rules are defined using MATRIXX Data Containers (MDCs) and are loaded into MATRIXX Engine as part of pricing and evaluated during query, purchase, and cancelation. During an offer purchase, requirement and exclusion criteria are evaluated, ensuring that rules defined in the offer or bundle and components included in the offers are evaluated against the subscriber, group, or device attributes defined in the eligibility rules. All eligibility requirements must be met, or the catalog item purchase is rejected.

Eligibility rules describe the conditions, including the location to search for the condition. For example, these locations can be features the subscriber has on the catalog item in their purchased item list, and values within the subscriber attributes.

To create an eligibility rule, you specify the object type and select whether the rule applies to an attribute or a feature.

Note: If the attribute or feature value is left blank, the rule checks whether the selected attribute or feature is present.

Defining Eligibility Rules Using Attributes

An attribute is based on an MDC and is used for eligibility verification. An attribute must be a simple field in the entity being evaluated or in its extension object. To define a rule using an attribute, you select the MDC container, select an MDC attribute name, and enter an alphanumeric attribute value for the rule.

Create an Eligibility Rule

In this example, you define an eligibility rule where the catalog item requires the subscriber attribute CustomSubscriber.Level to have a value of Gold.

Define the eligibility rule.

Create an eligibility rule GoldSubscriber, select Subscriber as the Object Type, and select Attribute as the Entity Type.
Select CustomSubscriber from Container Name, select Level from Attribute Name, and type Gold as the Value.

Assign the eligibility rule to the catalog item.

Select the catalog item, and click the Eligibility Rules tab.
Add the GoldSubscriber eligibility rule to the Requires Rules table.

Defining Eligibility Rules Using Eligibility Features

An eligibility feature is a property a catalog item provides for use in eligibility rule evaluation and is defined as an integer, decimal, or string value. To define a rule using a feature, you select from the defined eligibility features and enter the associated value. For eligibility features, a catalog item provides a feature, and another catalog item requires or excludes a feature. When evaluating an eligibility rule that uses features, features provided by the purchased items in the purchased item array are checked. Purchased items with an inactive status are excluded.

Define the Catalog Item Properties

In this example, you define the catalog item properties.

Define the catalog item.

Plan Type = Data
Data Provided GB = 5
IS BASE PLAN
Base Cost = 4.95

Define the Plan Type eligibility feature.

Create an eligibility feature, Plan Type, and select String as the Feature Type.
Create an eligibility rule, Plan Type Rule, select Subscriber as the Object Type, and select Feature as the Entity Type.
Select Plan Type from the Feature drop-down menu and enter the value Data.

Define the Data Provided GB eligibility feature.

Create an eligibility feature Data Provided GB, and select Integer as the Feature Type.
Create an eligibility rule Data Provided GB Rule, select Subscriber as the Object Type, and select Feature as the Entity Type.
Select Data Provided GB from the Feature drop-down menu, and enter the value 5.

Define the IS BASE PLAN eligibility feature.

Create an eligibility feature, IS BASE PLAN, and select String as the Feature Type.
Create a new eligibility rule, IS BASE PLAN Rule, select Subscriber as the Object Type, and select Feature as the Entity Type.
Select the IS BASE PLAN from the Feature drop-down menu.
Note: A feature might not need a value, for example, the IS BASE PLAN feature does not have a value.

Define the Base Cost eligibility feature.

Create an eligibility feature, Base Cost, and select Decimal as the Feature Type.
Create a new eligibility rule, Base Cost Rule, select Subscriber as the Object Type, and select Feature as the Entity Type. Select Base Cost from the Feature drop-down menu and enter the value 4.95.

Assign eligibility features to a catalog item.

Once you define your eligibility features, you assign them to the catalog item that provides the features.

Select the catalog item and click the Eligibility Features tab.
Add each eligibility feature and associated value to the Eligibility Features table:
- Plan Type = Data
- Data Provided GB = 5
- IS BASE PLAN
- Base Cost = 4.95

Assign eligibility rules to a catalog item.

Select the catalog item and click the Eligibility Rules tab.
Add the following eligibility rules to the Requires Rules table:
- Plan Type Rule
- Data Provided GB Rule
- IS BASE PLAN Rule
- Base Cost Rule

Enforcing Eligibility Rules

Eligibility rules are enforced during catalog item purchases, cancelations, and queries. If a catalog item does not pass the eligibility check, the catalog item purchase fails. Eligibility rule dependencies determine which catalog items are excluded based on items owned or being purchased.

An eligibility rule is a rule on an attribute or a feature. Rules in the Requires Rules list on a catalog item are evaluated using the AND condition, and rules in the Excludes Rules list on a catalog item are evaluated using the OR condition. Only rules that apply to the object type of the SubMan API request—subscription, group, or device—are evaluated.

For example, if a catalog item has eligibility rules with ObjectType=subscriber and ObjectType=group:

When a Subscriber API request is made, rules with ObjectType=subscriber are evaluated.
When a Group API request is made, rules with ObjectType=group are evaluated.
When a Device API request is made, there is no applicable rule, so rule evaluation is not performed.

Consider the example in Catalog Item Requirements and Exclusions and Figure 1. In this example, Subscriber A has the following attributes:

Subscriber Level = Gold
Subscriber Segment = B2B

Table 1. Catalog Item Requirements and Exclusions
Catalog Item ID	Eligibility Features	Requires	Excludes
1	Fast Download	Subscriber Level Gold Subscriber Segment B2B	Fast Download
2		Subscriber Level Gold Subscriber Segment B2B
3	Hotspot	Subscriber Level Gold Subscriber Segment B2B
4		Subscriber Level Silver Subscriber Segment B2B
5		Subscriber Level Gold Subscriber Segment B2B	Hotspot
6	Fast Download	Subscriber Level Gold Subscriber Segment B2B	Fast Download
7	Data3G
8		Data3G

Catalog item eligibility diagram — Figure 1. Catalog Item Eligibility

If a catalog item is rejected, the response includes the reason for eligibility failure.

You can perform a query on catalog items based on eligibility using the SubMan APIs. For more information about querying catalog item eligibility using the SubMan APIs, see the discussion about MtxPricingEligibilityRule in MATRIXX Subscriber Management API. For information about configuring eligibility rules, see My MATRIXX Help.