Get Billed Usage List

Gets billed usage for a list of segmentation labels for a bulk of devices. You can retrieve device billed usage either for an entire billing account, or up to 2,000 devices identified by either EID or VIN, but not both

For example, this API can be used for the automotive sector in cases where a streaming radio device is present.

Uses and Requirements

Allow customers to get billing usage for a list of usage segmentation labels for a specified billing cycle, or the most recent billing cycle if one is not specified.

Request Parameters

Parameter Type Description
AccountName
required		 string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
Labels string Wrapper for Label objects.
Label
required		 string The label associated with the device.
Name string The label associated with the device.
Value string The label value.
billingCycle The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent billing cycle information is provided.
billingCycle.year integer The year in which the billing cycle occurs.
billingCycle.month integer The number representing the month of the billing cycle. Valid values include integers between 1 and 12.

Callback Response Parameters

Parameter Type Description
Status string The status of the callback response. Valid values include
  • Success
  • Failed
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that associates the request with the results that are sent via a callback message
AccountName string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
AccountNumber string The billing account number.
BillingCycle The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent billing cycle information is provided.
BillingCycle.Year integer The year in which the billing cycle occurs.
billingCycle.Month integer The number representing the month of the billing cycle. Valid values include integers between 1 and 12.
Devices Wrapper Wrapper for device information.
Error.Code string Code associated with error.
Error.Message string Error message content and description.
Label Array of label names and label values Maximum of 2,000 objects are allowed.
Name string The name or type of label associated with the device.
Value string The label value.
RatePlanDescription string A description of the rate plan.
Label Array of label names and label values Maximum of 2,000 objects are allowed in the array.
Name string The name or type of label associated with the device.
Value string The label value.
DeviceIdentifier.Kind,
DeviceIdentifier.Identifier		 string The type and value of the device identifier. Valid value is:
  • EID - decimal, 20 digits
UnitOfMeasure string Indicates the method in which TotalDeviceBilledUsage is measured.
TotalDeviceBilledUsage integer Total of usage in units of measure.
TotalDeviceBilledChargeAmt integer The total dollar amount billed for the specified billing cycle.
UsageSegments Wrapper Breaks down the billing and usage details by rating groups.
RatingGroup> string An identifier for a grouping that breaks down billing and usage based on a contracted rate.
RatingGroupDetails Wrapper Lists charge and usage details for the billing cycle, by country code.
CurrentCycleDetails array Lists billing and usage details for the rating group for the specified billing cycle.
CountryCode string Code for the country that the usage and resulting charges are in.
Usage integer Total usage int he corresponding country for the billing cycle.
ChargeAmt integer The total dollar amount charged and usage information for the rating group by country code for the current billing cycle.
ChargeDescription string A description of the charges for the rating group by country code.
PageNumber integer The number of the page you are viewing in the callback.
TotalPages integer The total number of pages of information in the callback.
GoToState string Null for this callback.
DeviceProfileService string Null for this callback.
AlertService string Null for this callback.
InternalService string Null for this callback.
DiagnosticsService string Null for this callback.
Fault string Null for this callback.
Comment string Null for this callback.
Summary string Null for this callback.
CallbackCount integer Total number of callback requests.
MaxCallbackThreshold integer Maximum number of callbacks allowed.
ExtendedEnhancedConnectivityService string Null for this callback.
NiddService string Null for this callback.

Example SOAP Request Using Segmentation Label

 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:v2="http://nphase.com/unifiedwebservice/v2"
 xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
 xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
 <soapenv:Header>
    <token xmlns="http://nphase.com/unifiedwebservice/v2">f75bd90f-5d70-46fc-8bf9-0374680acfe5</token>
 </soapenv:Header>
 <soapenv:Body>
    <v2:GetBilledUsageList xmlns:v2="http://nphase.com/unifiedwebservice/v2">
        <!--Optional:-->
        <v2:Input>
        <!--Optional:-->
        <nph:AccountName xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">0342330389-00001</nph:AccountName>
        <!--Optional:-->
        <nph:Labels xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">
            <!--Zero or more repetitions:-->
            <nph1:Label xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
                <nph1:Name>VIN</nph1:Name>
                <nph1:Value>3MEFM08116R634856</nph1:Value>
            </nph1:Label>
            <nph1:Label xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
                <nph1:Name>VIN</nph1:Name>
                <nph1:Value>2N7DL3ZP2DF236943</nph1:Value>
            </nph1:Label>
        </nph:Labels>
        <nph:BillingCycle xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">
            <nph:Year>2020</nph:Year>
            <nph:Month>3</nph:Month>
        </nph:BillingCycle>
        </v2:Input>
    </v2:GetBilledUsageList>
</soapenv:Body>

Example SOAP Request using Device Identifiers

 <v2:GetBilledUsageList xmlns:v2="http://nphase.com/unifiedwebservice/v2">
    <!--Optional:-->
    <v2:Input>
        <!--Optional:-->
        <nph:AccountName xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">0342330389-00001</nph:AccountName>
        <!--Optional:-->
        <nph:DeviceIdentifiers>
            <!--Zero or more repetitions:-->
            <nph1:DeviceIdentifier>
                <nph1:Kind>EID</nph1:Kind>
                <nph1:Identifier>8991101200003204514</nph1:Identifier>
            </nph1:DeviceIdentifier>
        </nph:DeviceIdentifiers>
        <nph:BillingCycle xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">
            <nph:Year>2020</nph:Year>
            <nph:Month>3</nph:Month>
        </nph:BillingCycle>
    </v2:Input>
</v2:GetBilledUsageList>
</soapenv:Body>

Example Success Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
    <GetBilledUsageListResponse xmlns="http://nphase.com/unifiedwebservice/v2">
        <Output xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:RequestId>f75bd90f-5d70-46fc-1111-0374680acfe5</a:RequestId>
        </Output>
    </GetBilledUsageListResponse>
</s:Body>
</s:Envelope>

Example Fault Response 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
    <s:Fault>
        <faultcode>s:DeviceService.REQUEST_FAILED.UnexpectedError</faultcode>
        <faultstring xml:lang="en-US">Unexpected error occurred. Could not complete request. No record found for given criteria</faultstring>
    </s:Fault>
</s:Body>
</s:Envelope>

Example Callback Request Success

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
        <Status>Success</Status>
        <Username />
        <Password />
        <RequestId>0998abfc-404b-45ad-ba69-04c137518457</RequestId><Data><Data>
                <DeviceService>
                    <BilledUsage>
                        <AccountName>0342330389-00001</AccountName>
                        <AccountNumber>0342330389-00001</AccountNumber>
                        <BillingCycle>
                            <Year>2020</Year>
                            <Month>3</Month>
                        </BillingCycle>
                        <Devices>
                            <Error>
                                <Code>Label_NotFound</Code>
                                <Message>Label not found</Message>
                            </Error>
                            <Label>
                                <Name>VIN</Name>
                                <Value>3MEFM08116R634856</Value>
                            </Label>
                            <DeviceIdentifier xsi:nil="true" />
                        </Devices>
                        <Devices>
                            <RatePlanDescription>SNI Streaming Rate Plan Description</RatePlanDescription><Label>
                                <Name>VIN</Name>
                                <Value>3MEFM08116R634856</Value>
                            </Label>
                            <DeviceIdentifier>
                                <Kind>EID</Kind>
                                <Identifier>89148000005845275452</Identifier>
                            </DeviceIdentifier>
                            <UnitOfMeasure>MB</UnitOfMeasure>
                            <TotalDeviceBilledUsage>409886735</TotalDeviceBilledUsage>
                            <TotalDeviceBilledChargeAmt>2459319.27</TotalDeviceBilledChargeAmt>
                            <UsageSegments>
                                <RatingGroup>Streaming ACCT MGMT DATA</RatingGroup>
                                <RatingGroupDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27408385</Usage>
                                        <ChargeAmt>164450.23</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27303937</Usage>
                                        <ChargeAmt>163823.54</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                </RatingGroupDetails>
                            </UsageSegments>
                            <UsageSegments>
                                <RatingGroup>Streaming STRMG AUDIO DATA</RatingGroup>
                                <RatingGroupDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27408385</Usage>
                                        <ChargeAmt>164450.23</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27303937</Usage>
                                        <ChargeAmt>163823.54</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                </RatingGroupDetails>
                            </UsageSegments>
                            <UsageSegments>
                                <RatingGroup>Streaming SERVICES DATA</RatingGroup>
                                <RatingGroupDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27408385</Usage>
                                        <ChargeAmt>164450.23</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27303937</Usage>
                                        <ChargeAmt>163823.54</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                </RatingGroupDetails>
                            </UsageSegments>
                        </Devices>
                        <Devices>
                            <RatePlanDescription>SNI Streaming Rate Plan Description</RatePlanDescription><Label>
                                <Name>VIN</Name>
                                <Value>3MEFM08116R634856</Value>
                            </Label>
                            <DeviceIdentifier>
                                <Kind>EID</Kind>
                                <Identifier>89148000005845275452</Identifier>
                            </DeviceIdentifier>
                            <UnitOfMeasure>MB</UnitOfMeasure>
                            <TotalDeviceBilledUsage>409886735</TotalDeviceBilledUsage>
                            <TotalDeviceBilledChargeAmt>2459319.27</TotalDeviceBilledChargeAmt>
                            <UsageSegments>
                                <RatingGroup>Streaming ACCT MGMT DATA</RatingGroup>
                                <RatingGroupDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27408385</Usage>
                                        <ChargeAmt>164450.23</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27303937</Usage>
                                        <ChargeAmt>163823.54</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                </RatingGroupDetails>
                            </UsageSegments>
                            <UsageSegments>
                                <RatingGroup>Streaming STRMG AUDIO DATA</RatingGroup>
                                <RatingGroupDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27408385</Usage>
                                        <ChargeAmt>164450.23</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27304961</Usage>
                                        <ChargeAmt>163829.69</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27303937</Usage>
                                        <ChargeAmt>163823.54</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                </RatingGroupDetails>
                            </UsageSegments>
                            <UsageSegments>
                                <RatingGroup>Streaming SERVICES DATA</RatingGroup>
                                <RatingGroupDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27408385</Usage>
                                        <ChargeAmt>164450.23</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27303937</Usage>
                                        <ChargeAmt>163823.54</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                    <CurrentCycleDetails>
                                        <CountryCode>USA</CountryCode>
                                        <Usage>27305985</Usage>
                                        <ChargeAmt>163835.84</ChargeAmt>
                                        <ChargeDescription xsi:nil="true" />
                                    </CurrentCycleDetails>
                                </RatingGroupDetails>
                            </UsageSegments>
                        </Devices>
                        <PageNumber>1</PageNumber>
                        <TotalPages>1</TotalPages>
                    </BilledUsage>
                </DeviceService>
                <GoToState xsi:nil="true" />
                <DeviceProfileService xsi:nil="true" />
                <AlertService xsi:nil="true" />
                <InternalService xsi:nil="true" />
                <DiagnosticsService xsi:nil="true" />
                <Fault xsi:nil="true" />
                <Comment xsi:nil="true" />
                <Summary xsi:nil="true" />
                <CallbackCount>1</CallbackCount>
                <MaxCallbackThreshold>4</MaxCallbackThreshold>
                <ExtendedEnhancedConnectivityService xsi:nil="true" />
                <NiddService xsi:nil="true" />
            </Data></Data>
    </CallbackRequest>
</s:Body>
</s:Envelope>

Example Callback Failed

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
        <Status>Failed</Status>
        <Username />
        <Password />
        <RequestId>0998abfc-404b-45ad-ba69-04c137518457</RequestId>
        <Data><Data>
            <Fault>
            <q1:faultcode>UnifiedWebService.ACCESS_DENIED</q1:faultcode>
            <q1:faultstring>Account doesn't have access to the data</q1:faultstring>
            </Fault>
        </Data></Data>
    </CallbackRequest>
</s:Body>
</s:Envelope>