Service

Version: 1.33

A service is a subscription attached to an account.

Parameters

Extends: TractObject

Elements
Element Type Required? Description

CHOICE:

  • serviceDeactivationReason

  • serviceSuspensionReason

serviceDeactivationReason

serviceSuspensionReason

  

The service deactivation or suspension reason.

billingAccount

billingAccount

  

The billingaccount associated with this service.

serviceResource

serviceResource

  

The service resource (if any) for this service.

serviceResources

serviceResources

  

DEPRECATED

product

product

  

The product associated with this service.

parentService

Service

  

The parent service, if applicable.

servicePeriods

servicePeriods

  

The service period(s) for this service.

currentAgreementService

AgreementService

  

The current agreement (if any) associated with this service.

servicePrices

servicePrices

  

List of prices for this service.

nextService

Service

  

The next service (if any) to be associated with this billing account.

serviceUsageRules

serviceUsageRules

  

List of any usage rules associated with this service.

counters

counters

  

List of Charge, Event, or Rule counters associated with this service..

customFieldValues

customFieldValues

  

Any custom field values associated with this service.

addresses

    

The service address, if any.

childServices

Services

  

A list of any child services associated with this service.
Attributes
Attribute Required? Datatype Description

amount

Y

decimal

Cost of the service.

startDate

  

dateTime

Start date for this service.

endDate

  

dateTime

End date for this service.

status

  

ServiceStatus

SERVICE_ACTIVE

SERVICE_SUSPENDED

SERVICE_DEACTIVATED

SERVICE_PENDING

SERVICE_CANCELED

SERVICE_TRANSFERRED

SERVICE_REPLACED

SERVICE_TRIAL

SERVICE_SCHEDULED

statusDate

  

dateTime

The date this service obtained its current status.

description

  

string

A description of the service.

renewalCount

  

int

Record of how many times the service has been renewed. Count may include a scheduled renewal that has not yet occurred.

commitmentEndDate

  

dateTime

The date the commitment to this service ended or will end, based upon any agreements.

oldLevel

  

int

The prior level of the service.

currentLevel

  

int

The current level of the service.

quantity

  

decimal

The quantity of this service; how many services at this price.

consumePrepaidBalance

  

boolean

Whether this service consumes a prepaid balance.

Querying Service

For paged results, use the plural of the entity name (for example, billingAccounts, productCategories). For more information, refer to Understanding Queries.

Query Keys
Key Type

eid

Long

accountNum

String

billingAccountEid

Long

productEid

Long

agreementEid

Long

serviceResourceIdentifier

String

parentEid

Long

externalAccountNum

String

renewalCount

Integer

customFieldValueEid

Long

status

ServiceStatus

startDate

Timestamp

endDate

Timestamp

invoiceItemEid

Long

customFieldValue

String

customFieldEid

Long

previousServiceEid

Long

nextServiceEid

Long

usagePoolEid

Long

originalOrderEid

Long

originalOrderNum

String

originalOrderItemSequence

Long

*Required parameter pairings are as follows:

originalOrderEid, originalOrderItemSequence originalOrderNum, originalOrderItemSequenceoriginalOrderEid, originalOrderItemSequence originalOrderNum, originalOrderItemSequence.

REST Endpoints

getServices

GET

https://my.tractbilling.com/t/s/r/1.33/services

getService

GET

https://my.tractbilling.com/t/s/r/1.33/services/{eid}

getProductsCompatibleForChangeService

GET

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/compatibleForChangeService

updateService

PUT

https://my.tractbilling.com/t/s/r/1.33/services/{eid}

addAdjustment

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addAdjustment

cancelServiceScheduledCharges

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/cancelScheduledCharges

renewService

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/renew

suspendService

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/suspend

resumeService

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/resume

addAgreement

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addAgreement

addAddress

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addAddress

addServiceResource

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addServiceResource

deactivateService

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/deactivate

changePrice

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/changePrice

addServiceUsageRule

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addServiceUsageRule

addCounter

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addCounter

addCustomFieldValue

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addCustomFieldValue

removeCustomFieldValue

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/removeCustomFieldValue

addDiscountIdentifier

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/addDiscountIdentifier

removeAddress

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/removeAddress

changeQuantity

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/changeQuantity

changeServiceOneTimePriceCharges

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/changeScheduledOneTimePriceCharges

changeServiceServicePriceCharges

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/changeScheduledCharges

removeServiceResource

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/removeServiceResource

removeServiceUsageRule

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid}/removeServiceUsageRule

revertLastChangeQuantity

POST

https://my.tractbilling.com/t/s/r/1.33/services/{eid: \d+}/revertLastChangeQuantity

removeServiceResource

POST

https://my.tractbilling.com/t/s/r/1.31/services/{eid: \d+}/removeServiceResource

Sample Requests and Responses

SOAP

Add Service Resource to Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body>
      <ser:command>
       <ser:commandRequest>
         <dom:addServiceResourceToService>
          <dom:service eid="666444"/>
          <dom:serviceResource identifier="New Service Resource">
           <dom:category eid="553"/>  
           </dom:serviceResource>
         </dom:addServiceResourceToService>
        </ser:commandRequest>
      </ser:command>
    </soapenv:Body>
    </soapenv:Envelope>

Deactivate Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body>
      <ser:command>
       <ser:commandRequest>
         <dom:deactivateService>
          <dom:service eid="666444"/>
          <dom:reason eid="15"/>     
         </dom:deactivateService>
        </ser:commandRequest>
      </ser:command>
    </soapenv:Body>
    </soapenv:Envelope>

Renew Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:command>
            <ser:commandRequest>
                <dom:renewService>
                    <dom:service eid="99432">
                        <dom:billingAccount eid="7743221"/>
                    </dom:service>
                    <dom:order>
                        <dom:orderItems>
                            <dom:orderItem quantity="1" sequence="1"referenceId="Test_ID3">
                                <dom:product eid="88765"/>
                                <dom:selectedAgreement eid="3346"/>
                            </dom:orderItem>
                        </dom:orderItems>
                        <dom:billingAccount eid="7743221"/>
                        <dom:payments>
                            <dom:payment amount="10.00" description="Note - the price of the renew-to product must be exactly 10.00">
                                <dom:billingAccount eid="7743221"/>
                                <dom:creditCardPayment cardType="VISA" 
cardHolderFirstName="Mary" cardHolderMiddleName="M" cardHolderLastName="Smith" 
cardIdentifierNumber="4111111111111111" cardExpiration="12/2015" />
                            </dom:payment>
                        </dom:payments>
                    </dom:order>
                </dom:renewService>
            </ser:commandRequest>
        </ser:command>
    </soapenv:Body>
</soapenv:Envelope>

Suspend Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body>
      <ser:command>
       <ser:commandRequest>
         <dom:suspendService>
          <dom:service eid="666444"/>
          <dom:reason eid="3"/>     
         </dom:suspendService>
        </ser:commandRequest>
      </ser:command>
    </soapenv:Body>
    </soapenv:Envelope>

Resume Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body>
      <ser:command>
       <ser:commandRequest>
         <dom:resumeService>
          <dom:service eid="666444"/>   
         </dom:resumeService>
        </ser:commandRequest>
      </ser:command>
    </soapenv:Body>
    </soapenv:Envelope>

Add Counter to Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body> 
 <ser:command>
        <!--Optional:-->
        <ser:commandRequest>
            <dom:addCounterToService>
                <dom:service eid="2499697">
                </dom:service>
                <dom:usageChargeCounter name="First Counter" description="Counter Description" fromDate="2013-09-27T00:00:00.000-05:00" thruDate="2013-09-27T00:00:00.000-05:00" status="DRAFT" type="USAGE_CHARGE" entityRelationtype="SERVICE" amount="10" uom="MEGABYTE" threshold="20">
                    <!--  <dom:usageRuleCounter eid="?" name="?" description="?" fromDate="?" 
thruDate="?" status="?" type="?" entityRelationtype="?" amount="?" uom="?" threshold="?"> -->
                    <!--  <dom:usageEventCounter eid="?" name="?" description="?" fromDate="?" 
thruDate="?" status="?" type="?" entityRelationtype="?" event="?" threshold="?"> -->
                    <dom:servicePeriodCounterResetCriteria/> </dom:usageChargeCounter>
            </dom:addCounterToService>
        </ser:commandRequest>
    </ser:command>
 </soapenv:Body>
</soapenv:Envelope>

Add Custom Field Value to Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:command>
            <ser:commandRequest>
                <dom:addCustomFieldValueToService>
                    <dom:service eid="66095"/>
                    <dom:customFieldValue value="Yes">
                        <dom:customField eid="6"/>
                    </dom:customFieldValue>
                </dom:addCustomFieldValueToService>
            </ser:commandRequest>
        </ser:command>
    </soapenv:Body>
</soapenv:Envelope>

Add Discount Identifier to Service

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:command xmlns="http://www.tractbilling.com/billing/1.26/domain" xmlns:ns2="http://www.tractbilling.com/billing/1.26/service" xmlns:ns3="http://www.tractbilling.com/billing/1.26/domain/rest">
            <ns2:commandRequest>
                <addDiscountIdentifierToService>
                    <service amount="10.00000" description="Discount Product" eid="48531" queryScope="SHALLOW" renewalCount="0" startDate="2014-01-31T13:00:11.000-06:00" status="SERVICE_ACTIVE">
                        <billingAccount eid="39090" queryScope="EID"/>
                        <serviceResources elementCount="0" pageNumber="1" pageSize="50" totalElements="0" totalPages="0"/>
                        <product eid="608" queryScope="EID"/>
                        <servicePeriods elementCount="0" pageNumber="1" pageSize="50" totalElements="3" totalPages="1"/>
                        <servicePrices elementCount="0" pageNumber="1" pageSize="50" totalElements="1" totalPages="1"/>
                        <serviceUsageRules elementCount="0" pageNumber="1" pageSize="50" totalElements="0" totalPages="0"/>
                        <counters elementCount="0" pageNumber="1" pageSize="50" totalElements="0" totalPages="0"/>
                        <customFieldValues elementCount="0" pageNumber="1" pageSize="50" totalElements="0" totalPages="0"/>
                    </service>
                    <discountIdentifier eid="51992" identifier="DI-APITEST" queryScope="DEEP" status="ACTIVE" unlimited="true" uses="11">
                        <category eid="163" name="DiscountCategory_ACTIVE" queryScope="DEEP" status="ACTIVE" type="GENERICSRVCRESOURCE"/>
                    </discountIdentifier>
                </addDiscountIdentifierToService>
            </ns2:commandRequest>
        </ns2:command>
    </soap:Body>
</soap:Envelope>

Add Service Usage Rule to Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:command>
            <!-- Optional: -->
            <ser:commandRequest>
                <dom:addServiceUsageRuleToService>
                    <dom:service eid="68027"></dom:service>
                    <dom:formulaServiceUsageRule limit="100" usageUom="MEGABYTE" name="formula-table" order="3" proratedOnOrder="false" proratedOnCancel="false" rollOverType="None" allowanceType="Recurring" ruleType="TAPERED" status="ACTIVE" fieldName="text01" operator="Equals" fieldValue="test">
                        <dom:chargeCategory eid="223" />
                        <!-- Optional: -->
                        <dom:tableUsageRate uom="MEGABYTE" usageFieldName="text01">
                            <dom:rateTable eid="3" />
                        </dom:tableUsageRate>
                    </dom:formulaServiceUsageRule>
                </dom:addServiceUsageRuleToService>
            </ser:commandRequest>
        </ser:command>
    </soapenv:Body>
</soapenv:Envelope>

Change Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.tractbilling.com/billing/1_31/service">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:command>
            <ser:commandRequest>
                <dom:changeService effectiveDate="2013-10-15-05:00">
                    <dom:service eid="69509"/>
                    <dom:order>
                        <dom:orderItems>
                            <dom:orderItem quantity="1">
                                <!-- the product to change to -->
                                <dom:product eid="475"/>
                            </dom:orderItem>
                        </dom:orderItems>
                        <dom:billingAccount eid="31040"/>
                    </dom:order>
                </dom:changeService>
            </ser:commandRequest>
        </ser:command>
        <ser:authorize/>
    </soapenv:Body>
</soapenv:Envelope>

Change Service Price

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

Change Service Quantity

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ser="http://www.tractbilling.com/billing/1.32/service"xmlns:dom="http://www.tractbilling.com/billing/1.32/domain">
	<soapenv:Header/>
	<soapenv:Body>
		<ser:command>
			<!-- Optional: -->
			<ser:commandRequest>
				<dom:changeServiceQuantity newQuantity="2" effectiveDate="2013-10-21-05:00" >
					<dom:service eid="69398"></dom:service>
				</dom:changeServiceQuantity>
			</ser:commandRequest>
		</ser:command>
	</soapenv:Body>
</soapenv:Envelope>

Remove Custom Field Value from Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body>
      <ser:command>
       <ser:commandRequest>
         <dom:removeCustomFieldValueFromService>
          <dom:service eid="666444"/>
          <dom:customFieldValue eid="3"/>
         
         </dom:removeCustomFieldValueFromService>
        </ser:commandRequest>
      </ser:command>
    </soapenv:Body>
    </soapenv:Envelope>

Remove Service Resource from Service

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ser="http://www.tractbilling.com/billing/1_31/service"
    ">
    <soapenv:Header/>
    <soapenv:Body>
      <ser:command>
       <ser:commandRequest>
         <dom:removeServiceResourceFromService>
          <dom:service eid="666444"/>
          <dom:serviceResource eid="55"/>
         
         </dom:removeServiceResourceFromService>
        </ser:commandRequest>
      </ser:command>
    </soapenv:Body>
    </soapenv:Envelope>

Add Agreement To Service

<soapenv:Header/>
    <soapenv:Body>
        <ser:command>
            <ser:commandRequest>
                <dom:addAgreementToService>
                    <dom:service eid="2059070" />
                    <dom:agreementService endAction="RENEW_AGREEMENT" startDate="2014-07-06T00:00:00-06:00" preserveServicePrice="true">
                        <dom:agreement eid="10494" /> </dom:agreementService>
                </dom:addAgreementToService>
            </ser:commandRequest>
        </ser:command>
        <ser1:command xmlns:ser1="http://www.tractbilling.com/billing/1_31/service" />
   </soapenv:Body>

Query for Compatible Products for Change Service

<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>
<ser:commandRequest>
<compatibleForChangeService preserveAgreement="true">
<service eid="882"/>
</compatibleForChangeService>
</ser:commandRequest>
</ser:command>
<ser:authorize/>
<ser1:authorize xmlns:ser1="http://www.tractbilling.com/billing/1_31/service"/>
</soapenv:Body>
</soapenv:Envelope>

REST

Resume a Service

  • POST https://my.tractbilling.com/t/s/r/1.33/services/67255/resume

<resumeService xmlns="http://www.tractbilling.com/billing/1_31/domain">
    <service eid="67255"/>
</resumeService>

Suspend a Service

  • POST https://my.tractbilling.com/t/s/r/1.33/services/70001/suspend

<suspendService xmlns="http://www.tractbilling.com/billing/1_31/domain">
    <service eid="70001"/>
</suspendService>

Update a Service

  • PUT https://my.tractbilling.com/t/s/r/1.33/services/<eid>

<service eid="12345" description="This is an updated description now entered for this Service."
	xmlns="http://www.tractbilling.com/billing/1_31/domain"/>

Add Service Resource to a Service

  • POST https://my.tractbilling.com/t/s/r/1.33/services/111332/addServiceResource

<addServiceResourceToService xmlns="http://www.tractbilling.com/billing/1_31/domain">
    <service eid="111332"/>
    <serviceResource identifier="New Service Resource">
        <category eid="773"/>
    </serviceResource>
</addServiceResourceToService>

Remove a Service Resource From a Service

  • POST https://my.tractbilling.com/t/s/r/1.33/services/33779/removeServiceResource

<removeServiceResourceFromService xmlns="http://www.tractbilling.com/billing/1_31/domain">
    <service eid="33779"/>
    <serviceResource eid="39507"></removeServiceResourceFromService>

Add Agreement to Service

In the following example, the Service EID value of "2086894" and the Agreement EID of "2940" were learned through separate queries.

  • POST https://my.tractbilling.com/t/s/r/1.33/services/2086894/addAgreement

<addAgreementToService xmlns="http://www.tractbilling.com/billing/1_33/domain" startDate="2017-08-03T06:00:00-05:00">
	<service eid="2086894"/>
	<agreement eid="2940"/>
	<agreementConfiguration endDate="2017-08-21T06:00:00-05:00"/>
</addAgreementToService>

Renew Service

  • POST https://my.tractbilling.com/t/s/r/1.33/services/99432/renew

<renewService xmlns="http://www.tractbilling.com/billing/1_31/domain">
    <service eid="99432">
        <billingAccount eid="7743221"/>
    </service>
    <order>
        <orderItems>
            <orderItem quantity="1" sequence="1">
                <product eid="88765"/>
                <selectedAgreement eid="3346"/>
            </orderItem>
        </orderItems>
        <billingAccount eid="7743221"/>
        <payments>
            <payment amount="10.00" description="Note - the price of the renew-to product must be exactly 10.00">
                <billingAccount eid="7743221"/>
                <creditCardPayment cardType="VISA" 
cardHolderFirstName="Mary" cardHolderMiddleName="M" cardHolderLastName="Smith" 
cardIdentifierNumber="4111111111111111" cardExpiration="12/2015" />
            </payment>
        </payments>
    </order>
</renewService>

Deactivate a Service

Deactivating a Service is permanent, and the Service cannot be resumed or reactivated.

  • POST https://my.tractbilling.com/t/s/r/1.33/services/11332/deactivate

<deactivateService xmlns="http://www.tractbilling.com/billing/1_31/domain">
    <service eid="11332"/>
</deactivateService>

Query for Compatible Products for Change Service

  • GET /tract/s/r/1.32/services/534/compatibleForChangeService

Optional query parameter: preserveAgreement=true|false

Refer to the following topics for more information: