ProductUsageRule

Version: 1.33

Query ProductUsageRule directly for information, or query and use through Product, RecurringProductPrice, OneTimeProductPrice, FormulaProductUsageRule, GlobalProductUsageRule, MatchAllProductUsageRule.

Usage Events are governed by Usage Rules. Usage Rules detect a condition within a Usage Event and evaluate whether that condition is true or false. If the Usage Rule evaluates the condition as "true," an action occurs that could lead to a Customer charge. If the Usage Rule evaluates as "false," no action is taken and the event that is being evaluated passes to the next Usage Rule for evaluation.

To evaluate an event in the correct order, Usage Rules must be in a hierarchical order that you determine and change as needed. The customized Usage Rules and the order in which they are listed make up the Rate Plan.

Gotransverse has three types of Usage Rules:

  • Global Usage Rules -- complex Usage Rules that can be associated with, and used by any Product

  • Formula Usage Rules -- created as part of a Product definition and associated only with that Product, and uses equations and may use Lookup Tables

  • Match-All Usage Rules -- uses one of the following rates:

    • FlatUsageRate

    • PassThroughUsageRate - with the rate in the Event

    • Table including RateTable and UsageLookupTable

Usage Rules process events using the amount of usage reported, applying conditions and predefined Rates to the usage, and adding the results to the Customer's Billing Account for invoicing.

Further Gotransverse API information for this entity of ProductUsageRule:

Parameters

When you query an ProductUsageRule, the following table provides information about the values returned from the query:

Elements
Element Name Query
Key		 Element Type Field
Length		 Description

queryScope

QueryScope

 - -

Whether default query results are
overridden by QueryScope resulting
in SHALLOW or DEEP query results.
See QueryScope for details.

eid

Y

Long

System
Generated

System generated unique identity
number assigned to all entities in Gotransverse.

chargeCategory

UsagePriceCategory

 - -

Select the Usage Price Category.
See UsagePriceCategory for information.

Choice of one of the
following UsageRates:
-flatUsageRate
-tableUsageRate
-passThroughUsageRate

One of the following
UsageRates:
-FlatUsageRate
-TableUsageRate
-PassThroughUsageRate

 - -

Click on one of the following links
for more information:
-FlatUsageRate
-TableUsageRate
-PassThroughUsageRate

limit

decimal

As
Needed

usageUom

UsageDurationUom

 - -

Unit of measurement of the usage event to be measured
and charged to the Customer's BillingAccount.
See UsageDurationUom for list of units of measurement.

name

String

255

The name of the Product Usage Rule.

order

Int

As
Needed

proratedOnOrder

Boolean

Shown either:

"true"
(Yes)
or "false"
(No)

Is this usage rate prorated on Order or not?

YES, this is prorated upon Order. If the Order date
is into the billing cycle, the bill will be less than that of a
regular time period. (For example the service is $20 per month
and the service is ordered 15 days into the bill cycle.
If prorated, then only $10 is charged, rather than $20.)

NO, this is NOT prorated upon Order. Any date in the billing cycle
this item is ordered it will be the full price for the time period.
(For example, the service is $20 per month and the service is
ordered 29 days into a 30 day bill cycle. The Customer
would pay $20 for the 1 day of service, then the next month,
pay $20 for the month.)

proratedOnCancel

Boolean

Shown either:

"true"
(Yes)
or "false"
(No)

Is this usage rate prorated on Cancellation or not?

YES, this is prorated upon Cancellation. If the Cancellation
date is past the end of the billing cycle, the bill will be for the time
it was used. (For example the service is $60 per month
and the service is canceled 1 day past the end of a bill cycle.
If prorated on cancellation, then only $2 is charged, rather than $60.)

NO, this is NOT prorated upon Cancellation. Any date in
the billing cycle this item is canceled it will be the full price
for the time period. (For example, the service is $60 per month
and the service is canceled 1 day past bill cycle. The Customer
would pay $60 for the 1 day of service.)

rollOverType

RollOverType

255

One of the
following types:
- None
- Uncapped

The type of rollover. See RollOverType for definitions.

allowanceType

AllowanceType

255
One of the
following types: - Unlimited
- Recurring
- OneTime

The type of Allowance. See AllowanceType for definitions.

validFrom

dateTime

See
Data Types page
for dateTime
formats

The date and time the ProductUsageRule begins.

validTo

dateTime

See
Data Types page
for dateTime
formats

The date and time the ProductUsageRule ends.

ruleType

RuleType

255 One of the
following types:
- TAPERED
- TIERED

The type of Rule. See RuleType.

status

ProductUsageRuleStatus

255 One of the
following statuses:
- ACTIVE
- DRAFT

The status of the ProductUsageRuleStatus.

Entity ProductUsageRules

The entity ProductUsageRules enables you to see multiple pages of the entity ProductUsageRule.

Elements
Element Name Element Type Field Length Description

pageNumber

Integer

as needed

Shows the current page number.

pageSize

Integer

as needed

Shows the page size.

totalElements

Long

as needed

Shows the total number of items found.

elementCount

Integer

as needed

Shows the current count of the item
in the number of items that were found.

totalPages

Integer

as needed

Shows the total number of pages.

Select one:
matchAllOrderItemUsageRule
-formulaOrderItemUsageRule
-globalOrderItemUsageRule

MatchAllOrderItemUsageRule
-FormulaOrderItemUsageRule
-GlobalOrderItemUsageRule

 - -

Shows one of the following choices:
-matchAllOrderItemUsageRule
-formulaOrderItemUsageRule
-globalOrderItemUsageRule

Information for the related entity of ProductUsageRules:

  • Entity ProductUsageRules

How to Query for a ProductUsageRule

Query Key Information for SOAP and REST

Querying to see ProductUsageRules needs to include one of the following parameters. If you do not know the value for the parameter, query separately to learn the value.

Query Key Parameters

ProductUsageRule
Query Key Value Definition

eid

Long

The unique eid number for the ProductUsageRule.

productEid

Long

The unique eid of the Product.

productPriceEid

Long

The unique eid of the ProductPrice.

status

  

The status of the ProductUsageRule:
ACTIVE or DRAFT. See ProductUsageRuleStatus.
Query to Use
Query Query for Parameter Name and Value Returns
SimpleDataQuery ProductUsageRule <parameter name><parameter value> List of your ProcuctUsageRules for that parameter name and value.

SOAP Examples

SOAP Example Query

In the following example SOAP query, the parameter of productEid was used. The Product's EID value (in this example "1273"), was learned through a previous query on Product.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:query xmlns="http://www.tractbilling.com/billing/1_24/domain"xmlns:ns2="http://www.tractbilling.com/billing/1_24/service">
            <ns2:queryRequest>
                <simpleDataQuery startIndex="0" size="50">
                    <type>ProductUsageRule</type>
                    <parameter parameter="productEid" parameterValue="1273"/>
                </simpleDataQuery>
            </ns2:queryRequest>
        </ns2:query>
    </soap:Body>
</soap:Envelope>

Move Product Usage Rule Up

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service" xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:command>
         <!--Optional:-->
         <ser:commandRequest>
            <dom:moveProductUsageRuleUp>
               <dom:productUsageRule eid="96">
               </dom:productUsageRule>              
            </dom:moveProductUsageRuleUp>
        </ser:commandRequest>
      </ser:command>
   </soapenv:Body>
</soapenv:Envelope>

Move Product Usage Rule Down

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service" xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:command>
         <!--Optional:-->
         <ser:commandRequest>
            <dom:moveProductUsageRuleDown>
               <dom:productUsageRule eid="96">
               </dom:productUsageRule>              
            </dom:moveProductUsageRuleDown>
        </ser:commandRequest>
      </ser:command>
   </soapenv:Body>
</soapenv:Envelope>

Activate Product Usage Rule

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service" xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:command>
         <!--Optional:-->
         <ser:commandRequest>
            <dom:activateProductUsageRule>
               <dom:productUsageRule eid="116">
               </dom:productUsageRule>              
            </dom:activateProductUsageRule>
        </ser:commandRequest>
      </ser:command>
   </soapenv:Body>
</soapenv:Envelope>

Deactivate(End Date) Product Usage Rule

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service" xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:command>
         <!--Optional:-->
         <ser:commandRequest>
            <dom:deactivateProductUsageRule validTo="2016-06-04">
               <dom:productUsageRule eid="99">
               </dom:productUsageRule>              
            </dom:deactivateProductUsageRule>
        </ser:commandRequest>
      </ser:command>
   </soapenv:Body>
</soapenv:Envelope>

REST Examples

Query
GET https://my.tractbilling.com/t/s/r/1.24/productUsageRules/<eid>

GET https://my.tractbilling.com/t/s/r/1.24/productUsageRules?eid=<eid>
GET https://my.tractbilling.com/t/s/r/1.24/productUsageRules?productEid=<productEid>
GET https://my.tractbilling.com/t/s/r/1.24/productUsageRules?productPriceEid=<productPriceEid>
GET https://my.tractbilling.com/t/s/r/1.24/productUsageRules?status=<status>

REST Example Query and Response

The following example is a Query in REST for ProductUsageRule using a parameter of Product. The Product's EID value (in this example "1273"), was learned through a previous query on Product.

Query
GET https://my.tractbilling.com/t/s/r/1.24/productUsageRules?productEid=1273

The response shows the ProductUsageRule for this Product. This Product Name is "Tanning - 10 minutes per day" with
a description of "Tanning in a tanning bed for 10 minutes per day for a maximum of 60 minutes per week for Customers
who want to tan gradually. Tanning time rolls over to a maximum of 70 minutes."

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<productUsageRules xmlns="http://www.tractbilling.com/billing/1_24/domain/rest" xmlns:ns2="http://www.tractbilling.com/billing/1_24/domain" pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
    <ns2:matchAllProductUsageRule status="ACTIVE" limit="70.00000" usageUom="WEEK" name="Rollover of Tanning Minutes" order="1" proratedOnOrder="true" proratedOnCancel="true" rollOverType="Uncapped" allowanceType="Recurring" validFrom="2012-02-22T00:00:00-06:00" ruleType="TAPERED" eid="421">
        <ns2:chargeCategory name="Customer Tanning Usage Charge" priority="2" status="ACTIVE" eid="536"/>
        <ns2:flatUsageRate rate="0.60000" uom="MINUTE" validFrom="2012-02-22T00:00:00-06:00" eid="422"/>
    </ns2:matchAllProductUsageRule>
</productUsageRules>

Move Product Usage Rule Up

POST https://my.tractbilling.com/t/s/r/1.33/productUsageRules/96/moveUp

<dom:moveProductUsageRuleUp xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
               <dom:productUsageRule eid="96">
               </dom:productUsageRule>              
            </dom:moveProductUsageRuleUp>

Move Product Usage Rule Down

POST https://my.tractbilling.com/t/s/r/1.33/productUsageRules/96/moveDown

<dom:moveProductUsageRuleDown xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
               <dom:productUsageRule eid="96">
               </dom:productUsageRule>              
            </dom:moveProductUsageRuleDown>

Activate Product Usage Rule

POST https://my.tractbilling.com/t/s/r/1.33/productUsageRules/96/activate

<dom:activateProductUsageRule validTo="2016-06-03" xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
               <dom:productUsageRule eid="117">
               </dom:productUsageRule>              
            </dom:activateProductUsageRule>

Deactivate(End Date) Product Usage Rule

POST https://my.tractbilling.com/t/s/r/1.33/productUsageRules/99/deactivate/

<dom:deactivateProductUsageRule validTo="2016-06-03" xmlns:dom="http://www.tractbilling.com/billing/1_31/domain">
               <dom:productUsageRule eid="99">
               </dom:productUsageRule>              
            </dom:deactivateProductUsageRule>