Pricing Cache REST Services

Because pricing information loaded in the MATRIXX Engine does not change often, the RS Gateway creates a lazy-loaded pricing-information cache of this information. The RS Gateway invalidates entries in this cache after a configurable time (default is 5 minutes) and when the system detects a new pricing file has been loaded into the engine.

Note: The SubMan pricing APIs get loaded pricing information from a MATRIXX Engine. For information about the SubMan pricing APIs, see MATRIXX Subscriber Management API.

You can query a list of objects or information about a specific object using its ID. Each call is a GET command to the specific URL listed in JSON Pricing Cache URLs and XML Pricing Cache URLs.

In multi-tenant environments, append ?tenantId=tenant_ID to the URL to return only the requested information for that tenant. For example, to return a list of catalogs for Tenant1 only: http://localhost:8080/rsgateway/data/v3/cache/pricing/Catalog?tenantId=Tenant1. Append ?routeId=route_ID to specify the sub-domain where the tenant resides. When specifying a tenant, the caller must have permission to access the tenant information. RS Gateway maintains a pricing cache per-sub-domain, per-tenant on that sub-domain. Each pricing cache is separate. If you are making a REST call to the pricing cache, the combination of sub-domain and tenant information determines the cache used and that cache is populated by SubMan calls made to the MATRIXX Engine that enforces what you can see.

The API documentation is code-generated as described in the discussion about viewing the code-generated API documentation. The RS Gateway pricing cache expires loaded items after 5 minutes. After this time, any request reloads the pricing cache. To change the default expiration time, set the expiration field (in milliseconds) in the /opt/mtx/conf/rsgateway.yaml file:
pricingcache:
  expiration: 300000
Table 1. JSON Pricing Cache URLs
URL Description
rsgateway/data/json/cache/pricing/balance List of all balance templates in the pricing cache.
For example: 
{
  "Results": [
    {
      "$": "MtxPricingBalanceInfo",
      "BalanceId": 21007,
      "ClassId": 20006,
      "ClassName": "Postpaid Non-periodic Balance Class",
      "Name": "Bal0"
    },
    {
      "$": "MtxPricingBalanceInfo",
      "BalanceId": 21242,
      "ClassId": 20006,
      "ClassName": "Postpaid Non-periodic Balance Class",
      "Name": "Offer Priority nonrecuring 5 day duration"
    },
...
rsgateway/data/json/cache/pricing/balance/{BalanceId} Specific details for the balance indicated by the BalanceId.
For example: 
{
    "$": "PricingBalanceDetailInfo",
    "BalanceId": 21007,
    "Category": 2,
    "ClassId": 20006,
    "ClassName": "Postpaid Non-periodic Balance Class",
    "CreateNotificationType": "None",
    "DisplayPrecision": 2,
    "DisplayQuantityUnit": "sec",
    "EndRelativeCount": 6,
    "EndRelativeUnit": 4,
    "EndTimeAdjustType": "Allow",
    "EndType": "Relative",
    "InstanceCreatePolicy": 1,
    "IsActualCurrency": false,
    "IsAggregate": false,
    "IsCost": false,
    "IsDeviceSpecific": false,
    "IsMainBalance": false,
    "IsOnDemand": false,
    "IsPeriodic": false,
    "IsPrepaid": false,
    "IsRenewable": false,
    "Name": "Bal0",
    "NotificationProfileId": 1,
    "Precision": 0,
    "Priority": 0,
    "QuantityUnit": "seconds",
    "StartType": "Relative",
    "_resultCode": 0,
    "_resultText": "OK",
    "_resultType": "get"
}
rsgateway/data/json/cache/pricing/balanceClass List of all balance classes in the pricing cache.
For example: 
{
  "Results": [
    {
      "$": "MtxPricingBalanceClassInfo",
      "Id": 20006,
      "Name": "Postpaid Non-periodic Balance Class"
    },
    {
      "$": "MtxPricingBalanceClassInfo",
      "Id": 20010,
      "Name": "Postpaid seconds Balance Class"
    },
    {
      "$": "MtxPricingBalanceClassInfo",
      "Id": 20011,
      "Name": "Postpaid minutes Balance Class"
    },
...
rsgateway/data/json/cache/pricing/balanceClass/{BalanceClassId} Specific details for the balance class indicated by the BalanceClassId.
For example: 
{
  "$": "MtxPricingBalanceClassDetailInfo",
  "BalanceIdList": [
    21007,
    21242
  ],
  "Id": 20006,
  "Name": "Postpaid Non-periodic Balance Class",
  "_resultCode": 0,
  "_resultText": "Ok",
  "_resultType": "get"
}
rsgateway/data/json/cache/pricing/Catalog A list of all catalogs in the pricing cache. To return the list of catalog items in the catalog, you must include the catalog ID in the URL as shown in the next API.
For example:
{
"Results": [
{
    "$": "MtxPricingCatalogDetailInfo", 
    "CatalogId": 1, 
    "Correction": 4, 
    "Description": "Catalog of Cell Phones", 
    "EffectiveTime": '** removed **'
    "ExternalId": "CELL_PHONE", 
    "Name": "Phone Catalog", 
    "RequireList": [
        {
            "$": "MtxPricingEligibilityInt64Rule", 
            "EntityType": "feature", 
            "Name": "Is a Phone", 
            "ObjectType": "catalog_item", 
            "Value": 1
        }
    ], 
    "Rev": 0
}
     ], 
     "_resultCode": 0, 
     "_resultText": "OK", 
     "_resultType": "get"
 }
rsgateway/data/json/cache/pricing/Catalog/{id} Specific details for the catalog indicated by the {id}.
For example:
{
     "$": "MtxPricingCatalogDetailInfo", 
     "CatalogId": 1, 
     "CatalogItemList": [
{
	"$": "MtxPricingCatalogItemInfo", 
	"CatalogItemId": 14, 
	"DeferredSettlementPurchaseAllowed": true, 
	"HasPurchasedItemCycle": false, 
	"IsOneTime": true, 
	"Name": "OneTime Offer for iPhone X", 
	"PurchasePreActiveAllowed": false, 
	"TemplateId": 15, 
	"TemplateName": "OneTime Offer for Merchandise", 
	"TemplateType": "offer", 
	"TemplateVersion": 0, 
	"TemplateVersionName": "OneTime Offer for Merchandise"
}
     ], 
     "Correction": 4, 
     "Description": "Catalog of Cell Phones", 
     "EffectiveTime": '** removed **'
     "ExternalId": "CELL_PHONE", 
     "Name": "Phone Catalog", 
     "RequireList": [
{
        "$": "MtxPricingEligibilityInt64Rule", 
        "EntityType": "feature", 
        "Name": "Is a Phone", 
        "ObjectType": "catalog_item", 
        "Value": 1
}
     ], 
     "Rev": 0, 
     "_resultCode": 0, 
     "_resultText": "OK", 
     "_resultType": "get"
 }
rsgateway/data/json/cache/pricing/CatalogItem List of all catalog items in the pricing cache.
For example: 
{
  "Results": [
    {
      "$": "MtxPricingCatalogItemDetailInfo",
      "CatalogItemId": 62,
      "Correction": 0,
      "Description": "",
      "EffectiveTime": "2012-01-01T00:00:00.000000Z",
      "Name": "mtx_PC_GRANT_0003 - Billing Cycle Triggered",
      "Rev": 0,
      "TemplateAttr": {"$": "MtxTemplateAttr"},
      "TemplateCorrection": 0,
      "TemplateDescription": "",
      "TemplateEffectiveTime": "2012-01-01T00:00:00.000000Z",
      "TemplateId": 62,
      "TemplateName": "mtx_PC_GRANT_0003 - Billing Cycle Triggered",
      "TemplateRev": 0,
      "TemplateType": "offer",
      "TemplateVersion": 0,
      "TemplateVersionDescription": "",
      "TemplateVersionName": "mtx_PC_GRANT_0003 - Billing Cycle Triggered"
     },
     {
      "$": "MtxPricingCatalogItemDetailInfo",
      "CatalogItemId": 63,
      "Correction": 0,
      "Description": "",
      "EffectiveTime": "2000-01-01T00:00:00.000000Z",
      "Name": "Rate Table - Test #40",
      "Rev": 0,
      "TemplateAttr": {"$": "MtxTemplateAttr"},
      "TemplateCorrection": 0,
      "TemplateDescription": "",
      "TemplateEffectiveTime": "2000-01-01T00:00:00.000000Z",
      "TemplateId": 63,
      "TemplateName": "Rate Table - Test #40",
      "TemplateRev": 0,
      "TemplateType": "offer",
      "TemplateVersion": 0,
      "TemplateVersionDescription": "",
      "TemplateVersionName": "Rate Table - Test #40"
        }
        ],
      "_resultCode": 0,
      "_resultText": "OK",
      "_resultType": "get"
}
rsgateway/data/json/cache/pricing/CatalogItem/{id} Specific details for the catalog item indicated by the {id}.
For example: 
{
    "$": "MtxPricingCatalogItemDetailInfo",
    "CatalogItemId": 62,
    "Correction": 0,
    "Description": "",
    "EffectiveTime": "2012-01-01T00:00:00.000000Z",
    "Name": "mtx_PC_GRANT_0003 - Billing Cycle Triggered",
    "Rev": 0,
    "TemplateAttr": {"$": "MtxTemplateAttr"},
    "TemplateCorrection": 0,
    "TemplateDescription": "",
    "TemplateEffectiveTime": "2012-01-01T00:00:00.000000Z",
    "TemplateId": 62,
    "TemplateName": "mtx_PC_GRANT_0003 - Billing Cycle Triggered",
    "TemplateRev": 0,
    "TemplateType": "offer",
    "TemplateVersion": 0,
    "TemplateVersionDescription": "",
    "TemplateVersionName": "mtx_PC_GRANT_0003 - Billing Cycle Triggered",
    "_resultCode": 0,
    "_resultText": "OK",
    "_resultType": "get"
}
rsgateway/data/json/cache/pricing/group/user_role Returns all possible roles that can be used in the association with the group object.
rsgateway/data/json/cache/pricing/offers List of all product offers in the pricing cache.
For example: 
{
  "Results": [
    {
      "$": "OfferAndBundleInfo",
      "Description": "",
      "Id": 252,
      "IsBundle": false,
      "IsGlobal": false,
      "Name": "Offer Priority - Test 009 - A",
      "OfferDetails": {
        "$": "MtxPricingOfferDetailInfo",
        "CancelNotificationFlag": false,
        "CancelType": "Immediate",
        "ChargeCancelProrationType": "Full",
        "ChargePurchaseProrationType": "Full",
        "ChargeRequiredBalanceFlag": false,
        "Correction": 5,
        "Description": "",
        "EffectiveTime": "2000-01-01T00:00:00.000000Z",
        "EndType": "None",
        "ExpirationPolicy": "none",
        "GrantCancelProrationType": "Full",
        "GrantPurchaseProrationType": "Full",
        "IsGlobal": false,
        "IsOneTime": false,
        "IsSupplemental": false,
        "Name": "Offer Priority - Test 009 - A",
        "NoSuspendFlag": false,
        "OfferId": 252,
        "OfferRev": 0,
        "Priority": 10,
        "PurchaseNotificationFlag": false,
        "RequiredBalanceArray": [21225],
        "RequiredBalanceInfoArray": [
          {
            "$": "MtxRequiredBalance",
            "BalanceId": 21225,
            "ClassId": 20047
          }
        ],
        "ServiceTypeId": 2,
        "StartType": "None",
        "Version": 0,
        "VersionDescription": "",
        "VersionName": "Offer Priority - Test 009 - A"
      },
      "Version": 0
    },
...
rsgateway/data/json/cache/pricing/offers/{OfferId} Specific details for the product offer indicated by the OfferId.
For example: 
{
    "$": "OfferAndBundleInfo",
    "Description": "",
    "Id": 252,
    "IsBundle": false,
    "IsGlobal": false,
    "Name": "Offer Priority - Test 009 - A",
    "OfferDetails": {
        "$": "MtxPricingOfferDetailInfo",
        "CancelNotificationFlag": false,
        "CancelType": "Immediate",
        "ChargeCancelProrationType": "Full",
        "ChargePurchaseProrationType": "Full",
        "ChargeRequiredBalanceFlag": false,
        "Correction": 5,
        "Description": "",
        "EffectiveTime": "2000-01-01T00:00:00.000000Z",
        "EndType": "None",
        "ExpirationPolicy": "none",
        "GrantCancelProrationType": "Full",
        "GrantPurchaseProrationType": "Full",
        "IsGlobal": false,
        "IsOneTime": false,
        "IsSupplemental": false,
        "Name": "Offer Priority - Test 009 - A",
        "NoSuspendFlag": false,
        "OfferId": 252,
        "OfferRev": 0,
        "Priority": 10,
        "PurchaseNotificationFlag": false,
        "RequiredBalanceArray": [21225],
        "RequiredBalanceInfoArray": [
            {
                "$": "MtxRequiredBalance",
                "BalanceId": 21225,
                "ClassId": 20047
            }
        ],
        "ServiceTypeId": 2,
        "StartType": "None",
        "Version": 0,
        "VersionDescription": "",
        "VersionName": "Offer Priority - Test 009 - A"
    },
    "Version": 0,
    "_resultCode": 0,
    "_resultText": "Ok",
    "_resultType": "get"
}
rsgateway/data/json/cache/pricing/offers/{OfferId}/{version} Specific details for the product offer indicated by the OfferId and version.

See the response above for version 0 of offer 252.

rsgateway/data/json/cache/pricing/billingCycle List of all billing cycle templates in the pricing cache.
For example: 
{
  "Results": [
    {
      "$": "MtxPricingBillingCycleInfo",
      "Id": 2011,
      "Name": "2011"
    },
    {
      "$": "MtxPricingBillingCycleInfo",
      "Id": 2013,
      "Name": "2013"
    },
...
rsgateway/data/json/cache/pricing/billingCycle/{BillingCycleId} Specific details for the billing cycle indicated by the BillingCycleId.
For example: 
{
  "$": "MtxPricingBillingCycleDetailInfo",
  "DatePolicy": 1,
  "Id": 2011,
  "Interval": 1,
  "Name": "2011",
  "Period": 2,
  "_resultCode": 0,
  "_resultText": "Ok",
  "_resultType": "get"
}
rsgateway/data/json/cache/pricing/lifecycle/device Returns the device status life cycle.
For example: 
{
  "Results": [
    {
      "$": "MtxPricingStatusInfo",
      "Description": "Active",
      "Status": 1
    },
    {
      "$": "MtxPricingStatusInfo",
      "Description": "Inactive",
      "Status": 2
    },
    {
      "$": "MtxPricingStatusInfo",
      "Description": "Suspended",
      "Status": 3
    },
...
rsgateway/data/json/cache/pricing/lifecycle/group Returns the group status life cycle.

See the device status life cycle values above for an example.

rsgateway/data/json/cache/pricing/lifecycle/subscriber Returns the group status life cycle.

See the device status life cycle values above for an example.

rsgateway/data/json/cache/pricing/notification List of all notification profiles in the pricing cache.
rsgateway/data/json/cache/pricing/notification/{NotificationProfileId} Specific details for the notification profile indicated by the NotificationProfileId.
rsgateway/data/json/cache/pricing/serviceType List of all service types in the pricing cache.
For example: 
{
  "Results": [
    {
      "$": "MtxPricingServiceTypeInfo",
      "Id": 1000,
      "Name": "Root Event"
    },
    {
      "$": "MtxPricingServiceTypeInfo",
      "Id": 20,
      "Name": "non-recurring",
      "ParentId": 1000
    },
    {
      "$": "MtxPricingServiceTypeInfo",
      "Id": 10,
      "Name": "recurring",
      "ParentId": 1000
    },
...
rsgateway/data/json/cache/pricing/serviceType/{ServiceTypeId} Specific details for the service type indicated by the ServiceTypeId.
For example: 
{
    "$": "MtxPricingServiceTypeDetailInfo",
    "DefaultAuthQuantity": 0.0000,
    "DefaultAuthQuantityUnit": "none",
    "DefaultQuotaValidityTime": 86400,
    "DefaultReAuthQuantity": 0.0000,
    "DefaultReAuthQuantityUnit": "none",
    "EventTypeId": 5,
    "HasAggregationQuantityLimit": false,
    "Id": 10,
    "IsAggregationBySession": false,
    "IsAggregationByTime": false,
    "IsQuotaAdaptive": false,
    "MaxAuthQuantity": "infinity",
    "MaxAuthQuantityUnit": "none",
    "MaxQuotaValidityTime": 86400,
    "MinAuthQuantity": 0.0000,
    "MinAuthQuantityUnit": "none",
    "MinQuotaValidityTime": 1,
    "Name": "recurring",
    "ParentId": 1000,
    "QuantityType": "actual_duration",
    "QuantityUnits": "seconds",
    "RatingQuantityType": "actual duration",
    "UseDefaultAuthQuantity": false,
    "_resultCode": 0,
    "_resultText": "Ok",
    "_resultType": "get"
}
rsgateway/data/json/cache/pricing/subscription/user_role Returns all possible roles that can be used in the association with the subscription object.
rsgateway/data/json/cache/pricing/user/user_role Returns all possible roles that can be used in the association with the user object.
Table 2. XML Pricing Cache URLs
URL Description
rsgateway/data/v3/cache/pricing/Catalog List of all catalogs in the pricing cache.
rsgateway/data/v3/cache/pricing/Catalog/{id} Specific details for the catalog indicated by the {id}.
rsgateway/data/v3/cache/pricing/CatalogItem List of all catalog items in the pricing cache.
rsgateway/data/v3/cache/pricing/CatalogItem/{id} Specific details for the catalog item indicated by the {id}.
rsgateway/data/v3/cache/pricing/Contract/{id} Specific details for the contract indicated by the {id}.

The DisplayQuantityUnit field is added to the service responses and is populated according to the following rules:

  • If a balance has metadata defined, and that metadata has a String metadata attribute named MtxUnits, the value of this metadata attribute is returned as the DisplayQuantityUnit value.
  • If the balance does not have metadata defined:
    • If the balance is a currency balance, the description field value of the currency balance class is returned.
    • If the balance has a quantity unit defined, that value is returned.

For details about each of the pricing cache APIs, generate the Java API bindings using the JavaApiGenerator.jar program. For more information, see the discussion about using the MATRIXX Java API in MATRIXX Subscriber Management API.