OrderItemUsageRule

Version: 1.33

Query OrderItemUsageRule directly for information, or query and use through FormulaOrderItemUsageRule, GlobalOrderItemUsageRule, and MatchAllOrderItemUsageRule.

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 OrderItemUsageRule:

Parameters

When you query an OrderItemUsageRule, 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

40

The name of the OrderItemUsageRule.

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.

allowanceType

AllowanceType

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

The type of Allowance. See AllowanceType.

validFrom

dateTime

See
Data Types page
for dateTime
formats

The date and time the OrderItemUsageRule begins.

validTo

dateTime

See
Data Types page
for dateTime
formats

The date and time the OrderItemUsageRule ends.

ruleType

RuleType

255
One of the
following types:
- TAPERED
- TIERED

The type of Rule. See RuleType.

status

Y

OrderItemUsageRuleStatus

255
One of the
following statuses:
- ACTIVE
- DRAFT

The status of the OrderItemUsageRuleStatus.

Entity OrderItemUsageRules

The entity OrderItemUsageRules enables you to see multiple pages of the entity OrderItemUsageRule.

OrderItemUsageRule
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 OrderItemUsageRules:

  • Entity OrderItemUsageRules

How to Query for an OrderItemUsageRule

Query Key Information for SOAP and REST

Querying to see OrderItemUsageRules 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

OrderItemUsageRule
Query Key Value Definition

eid

Long

The unique eid number for the OrderItemUsageRule.

orderItemEid

Long

The unique eid of the Order Item.

status

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

SOAP Example Query and Response

In the following example SOAP query, the parameter of orderItemEid was used. The Order Item's EID value (in this example "21130"), was learned through a previous query on OrderItem.

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

The response shows that this particular Order Item does not have an OrderItemUsageRule:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:queryResponse xmlns="http://www.tractbilling.com/billing/1_31/domain" xmlns:ns2="http://www.tractbilling.com/billing/1_31/service">
            <ns2:return successful="true">
                <orderItemUsageRules pageNumber="1" pageSize="50" totalElements="0" 
elementCount="0" totalPages="0"/>
            </ns2:return>
        </ns2:queryResponse>
    </soap:Body>
</soap:Envelope>

REST Mount Point and Parameters

Query
GET https://my.tractbilling.com/t/s/r/1.33/orderItemUsageRules/<eid>

GET https://my.tractbilling.com/t/s/r/1.33/orderItemUsageRules?eid=<eid>
GET https://my.tractbilling.com/t/s/r/1.33/orderItemUsageRules?orderItemEid=<orderItemEid>
GET https://my.tractbilling.com/t/s/r/1.33/orderItemUsageRules?status=<status>

REST Example Query and Response

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

Query
GET https://my.tractbilling.com/t/s/r/1.33/orderItemUsageRules?orderItemEid=21130

The response shows that this particular Order Item does not have an OrderItemUsageRule:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orderItemUsageRules  
xmlns:ns2="http://www.tractbilling.com/billing/1_31/domain" 
pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>