UsageInvoiceItem

Version: 1.33

UsageInvoiceItem is a charge for Usage of the Service that appears on the Invoice. An Invoice may or may not have one (1) or more UsageInvoiceItem on it, depending on whether or not there are any additional fees in that billing period.

usageInvoiceItem can be queried directly, or through the Invoice. Each UsageInvoiceItem includes at least one InvoiceItemCharge.

Additional Fee Invoice Items are one of six types of Invoice Items:

  • AdditionalFeeInvoiceItem

  • AdjustmentInvoiceItem

  • ProductInvoiceItem

  • ServiceInvoiceItem

  • TaxInvoiceItem

  • UsageInvoiceItem

Parameters

Each UsageInvoiceItem shown from the Query shows information for a number of elements in the entity. The following table shows the elements, details of the elements, and brief descriptions.

Elements
Element Name Element Type Field Length Description

queryScope

QueryScope

- -

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

eid

Long

System Generated

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

invoiceItemCharges

Sequence of InvoiceItemCharges

- -

Each item charged (Product on a customer's Order) can have multiple charges for example Price, Tax, and so forth.

quantity

Int

As needed

For non-serialized subscription or one-time Products,
which can be purchased in quantities of one or more;
this is the number of subscriptions (for example,
number of seats) that have been ordered.

unitAmount

Decimal

As needed

Cost of one item.

totalAmount

Decimal

As needed

Cost of all the items. If there is only one item this amount is the same as unitAmount.

description

String

255

A description of the Invoice Item.

taxable

Boolean

Shows either: "true" (Yes) or "false" (No)

Is the item taxable or not?

YES, the item IS taxable.

NO, the item is NOT taxable.

proratedPercentage

Decimal

As needed

Not used at this time.

chargeStartDate

dateTime

Refer to Data Types for dateTime formats.

The date and time the charges started.

chargeEndDate

dateTime

Refer to Data Types for dateTime formats.

The date and time the charges ended.

lineItemType

String

255

Not used at this time.

service

Service

- -

The Service on which the Usage occurs. Refer to Service and Usage for more information.

The dateTime format: yyyy-mm-ddThh:mm:ss.sss-06:00 The GMT offset is 6 hours. For example, 2011-01-28T16:17:22.234-06:00. Refer to Data Types for further information and for a list of dateTime formats accepted by Gotransverse.

Entity UsageInvoiceItems

The entity UsageInvoiceItems enables you to see multiple entries of the entity UsageInvoiceItems.

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.

invoiceItem

UsageInvoiceItem

- -

Shows the list of UsageInvoiceItems.

Entity InvoiceItems

The entity InvoiceItems enables you to see multiple entries of all the entities in InvoiceItems.

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.

invoiceItem

Includes:

AdditionalFeeInvoiceItem

AdjustmentInvoiceItem

ProductInvoiceItem

ServiceInvoiceItem

TaxInvoiceItem

UsageInvoiceItem

- -

Shows the list of InvoiceItems.

Information for the related entities:

  • Entity UsageInvoiceItems

  • Entity InvoiceItems

Query a UsageInvoiceItem

Query Key Information for SOAP and REST

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

Query Key Parameters - UsageInvoiceItem
Query Key Value Definition

eid

Long

The eid number of the UsageInvoiceItem.

invoiceEid

Long

The eid number of the Invoice.

invoiceNum

String

The unique number of the Invoice.

service

Long

The eid number of the Service.
Query
Query to Use Query for Parameter Name and Value Returns

SimpleDataQuery

UsageInvoiceItem

<parameter name><parameter value>

List of your UsageInvoiceItems for that parameter and value.

SOAP Example Query and Response

SOAP Query and Response of UsageInvoiceItem Using Parameter InvoiceNum

In the following example SOAP query, the parameter of servicecEid was used. The Service EID Number (in this example "2082294"), was learned through a previous query on Service.

<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 queryScope="SHALLOW">
                <simpleDataQuery>
                    <type>UsageInvoiceItem</type>
                    <parameter parameter="serviceEid" parameterValue="2082294"/>
                </simpleDataQuery>
            </ns2:queryRequest>
        </ns2:query>
    </soap:Body>
</soap:Envelope>

This was the response:

<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">
                <usageInvoiceItems pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
                    <usageInvoiceItem quantity="1" unitAmount="20.00" totalAmount="20.00" taxable="true" chargeStartDate="2014-06-05T00:00:00.000-05:00" chargeEndDate="2014-06-06T00:00:00.000-05:00" lineItemType="Usage" type="USAGE" eid="8877838" queryScope="SHALLOW">
                        <invoiceItemCharges pageNumber="1" pageSize="50" 
totalElements="0" elementCount="0" totalPages="0"/>
                        <service eid="2082294" queryScope="EID"/>
                    </usageInvoiceItem>
                </usageInvoiceItems>
            </ns2:return>
        </ns2:queryResponse>
    </soap:Body>
</soap:Envelope>

SOAP Query and Response of InvoiceItem Using Parameter InvoiceNum

In the following example SOAP query, the parameter of invoiceNum was used. The Invoice Number (in this example "111439627"), was learned through a previous query on Invoice.

<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>InvoiceItem</type>
                    <parameter parameter="invoiceNum" parameterValue="111439627"/>
                </simpleDataQuery>
            </ns2:queryRequest>
        </ns2:query>
    </soap:Body>
</soap:Envelope>

This was the response: 

<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">
                <invoiceItems pageNumber="1" pageSize="50" totalElements="3" elementCount="3" totalPages="1">
                    <invoiceItem quantity="1" unitAmount="0.99000" totalAmount="0.99000" taxable="false" proratedPercentage="100.00000" chargeStartDate="2012-01-06T12:08:15-06:00" chargeEndDate="2012-02-01T00:00:00-06:00" lineItemType="Product Sale" eid="317427">
                        <invoiceItemCharges pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
                    </invoiceItem>
                    <invoiceItem quantity="5" unitAmount="0.99000" totalAmount="4.95000" taxable="false" proratedPercentage="100.00000" chargeStartDate="2012-01-06T12:08:15-06:00" chargeEndDate="2012-02-01T00:00:00-06:00" lineItemType="Product Sale" eid="317427">
                        <invoiceItemCharges pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
                    </invoiceItem>
                    <invoiceItem quantity="5" unitAmount="0.99000" totalAmount="4.95000" taxable="false" proratedPercentage="100.00000" chargeStartDate="2012-02-01T00:00:00-06:00" chargeEndDate="2012-03-01T00:00:00-06:00" lineItemType="Product Sale" eid="317427">
                        <invoiceItemCharges pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
                    </invoiceItem>
                </invoiceItems>
            </ns2:return>
        </ns2:queryResponse>
    </soap:Body>
</soap:Envelope>

REST Mount Point and Parameters

Query

  • GET https://my.tractbilling.com/t/s/r/1.33/usageInvoiceItems/<eid>

  • GET https://my.tractbilling.com/t/s/r/1.33/usageInvoiceItems?eid=<eid>

  • GET https://my.tractbilling.com/t/s/r/1.33/usageInvoiceItems?invoiceNum=<invoiceNum>

  • GET https://my.tractbilling.com/t/s/r/1.33/usageInvoiceItems?invoiceEid=<invoiceEid>

  • GET https://my.tractbilling.com/t/s/r/1.33/usageInvoiceItems?service=<service>

To see all six types of Invoice Items, use the following mount points:

Query

  • GET https://my.tractbilling.com/t/s/r/1.33/invoiceItems/<eid>

  • GET https://my.tractbilling.com/t/s/r/1.33/invoiceItems?eid=<eid>

  • GET https://my.tractbilling.com/t/s/r/1.33/invoiceItems?invoiceNum=<invoiceNum>

GET https://my.tractbilling.com/t/s/r/1.33/invoiceItems?invoiceEid=<invoiceEid>

REST Example Queries and Responses

REST Query and Response of UsageInvoiceItem Using Parameter InvoiceNum

In the following example REST query, the parameter of serviceEid was used. The Service EID Number (in this example "2082294"), was learned through a previous query on Service.

  • GET https://my.tractbilling.com/t/s/r/1.33/usageInvoiceItems?serviceEid=2082294

This was the response (line breaks and formatting added for ease of reading):

<usageInvoiceItems xmlns:ns2="http://www.tractbilling.com/billing/1_31/domain" pageNumber="1" pageSize="50" totalElements="1" elementCount="1" totalPages="1">
    <usageInvoiceItem quantity="1" unitAmount="20.00" totalAmount="20.00" taxable="true" chargeStartDate="2014-06-05T00:00:00.000-05:00" chargeEndDate="2014-06-06T00:00:00.000-05:00" lineItemType="Usage" type="USAGE" eid="8877838" queryScope="SHALLOW">
        <ns2:invoiceItemCharges pageNumber="1" pageSize="50" 
totalElements="0" elementCount="0" totalPages="0"/>
        <ns2:service eid="2082294" queryScope="EID"/>
    </usageInvoiceItem>
</usageInvoiceItems>

REST Query and Response of InvoiceItem Using Parameter InvoiceNum

In the following example REST query, the parameter of invoiceNum was used. The Invoice Number (in this example "111439627"), was learned through a previous query on Invoice.

  • GET https://my.tractbilling.com/t/s/r/1.33/invoiceItems?invoiceNum=111439627

This was the response (line breaks and formatting added for ease of reading):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<invoiceItems xmlns:ns2="http://www.tractbilling.com/billing/1_31/domain" pageNumber="1" pageSize="50" totalElements="3" elementCount="3" totalPages="1">
    <ns2:invoiceItem quantity="1" unitAmount="0.99000" totalAmount="0.99000" taxable="false" proratedPercentage="100.00000" chargeStartDate="2012-01-06T12:08:15-06:00" chargeEndDate="2012-02-01T00:00:00-06:00" lineItemType="Product Sale" eid="317427">
        <ns2:invoiceItemCharges pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
    </ns2:invoiceItem>
    <ns2:invoiceItem quantity="5" unitAmount="0.99000" totalAmount="4.95000" taxable="false" proratedPercentage="100.00000" chargeStartDate="2012-01-06T12:08:15-06:00" chargeEndDate="2012-02-01T00:00:00-06:00" lineItemType="Product Sale" eid="317427">
        <ns2:invoiceItemCharges pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
    </ns2:invoiceItem>
    <ns2:invoiceItem quantity="5" unitAmount="0.99000" totalAmount="4.95000" taxable="false" proratedPercentage="100.00000" chargeStartDate="2012-02-01T00:00:00-06:00" chargeEndDate="2012-03-01T00:00:00-06:00" lineItemType="Product Sale" eid="317427">
        <ns2:invoiceItemCharges pageNumber="1" pageSize="50" totalElements="0" elementCount="0" totalPages="0"/>
    </ns2:invoiceItem>
</invoiceItems>