POST /devices/usage/actions/billedusage/listGets billed usage for for either multiple devices or an entire billing account.
The BilledUsageList API has the following limitations:
Customers who have previously been required to associate a usage segmentation label with a device to retrieve billing for that segment will still be required to create a segmentation label. See Set Usage Segmentation Labels.
Both this API endpoint and billedusage are currently in use by the automotive sector. Please note that these API endpoints are only available on a limited basis.
You must register for the DeviceService callback service to receive the callback response.
POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/billedusage/listNone.
The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization required |
string | HTTP Authorization bearer token. |
| VZ-M2M-Token required |
string | A valid session token returned by POST /session/login. |
| Content-Type required |
string | Must be application/json. |
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName required |
string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. |
| labels If getting billing for multiple devices, required if not specifying deviceId |
array | Maximum of 2,000 objects (label names and values) are allowed in the array. |
| label.name required |
Varchar(20) | The label associated with the device. You can only provide either label or deviceId. Not both. |
| label.value required |
Varchar (50) | The label value. |
| deviceId required if not specifying label |
object | An identifier for a single device. You can only provide either label or deviceId. Not both. |
| deviceId.kind, deviceId.id If getting billing for multiple devices, required if not specifying label* |
string | The type and value of the device identifier.
|
| billingCycle | object | The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent completed 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. |
| includeQosDetails optional |
boolean | This flag indicates if Quality of Service (QoS) information will be included in the callback. Note: This is for RTR accounts only. |
{
"accountName": "0000123456-00001",
"labels": [
{
"name": "VIN",
"value": "16-digit Vehicle ID number"
},
{
"name": "VIN",
"value": "16-digit Vehicle ID number"
}
],
"deviceIds": [
{
"kind": "EID",
"id": "the Electronic ID of the device"
},
{
"kind": "EID",
"id": "the Electronic ID of the device"
}
],
"billingCycle": {
"year": 2020,
"month": 3
}
"includeQosDetails" : "true"
}
Status 200
{
"requestId":"0998abfc-404b-45ad-ba69-04c137518457"
}
| Parameter Name | Data Type | Description |
|---|---|---|
| requestId |
string | A unique string that associates the request with the results that are sent via a callback message. |
| Parameter Name | Data Type | Description |
|---|---|---|
| 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. |
| deviceResponse |
object | Contains all of the responses for the callback. |
deviceResponse. billedUsageResponse |
object | Contains the account information and the billing period being queried. |
deviceResponse. billedUsageResponse. accountName |
string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. |
deviceResponse. billedUsageResponse. billingCycle |
object | The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent completed billing cycle information is provided. |
deviceResponse. billedUsageResponse. billingCycle. year |
integer | The year in which the billing cycle occurs. |
deviceResponse. billedUsageResponse. billingCycle. month |
integer | The number representing the month of the billing cycle. Valid values include integer values between 1 and 12. |
deviceResponse. billedUsageResponse. devices |
array | An array of all the devices responding in the callback. |
deviceResponse. billedUsageResponse.. devices.deviceId |
object | An identifier for a single device. |
deviceResponse. billedUsageResponse.. devices. deviceId.kind, billedUsageResponse.. devices. deviceId.id |
string | The type and value of the device identifier.
|
deviceResponse. billedUsageResponse.. devices.deviceId.oemName |
string | The engagement name of the manufacturer Note: This is only returned for usageSegments |
deviceResponse. billedUsageResponse.. devices.label |
array | label name and value objects. |
deviceResponse. billedUsageResponse.. devices. label.name |
Varchar(20) | The label associated with the device. |
deviceResponse. billedUsageResponse.. devices. label.value |
Varchar (50) | The label value associated with the device. |
deviceResponse. billedUsageResponse. devices.ratePlanDescription |
string | A description of the rate plan. |
deviceResponse. billedUsageResponse. devices.totalBilledAmount |
integer | The total dollar amount billed for the specified billing cycle. |
deviceResponse. billedUsageResponse. devices.totalBilledUsage |
integer | Total of usage in units of measure. |
deviceResponse. billedUsageResponse. devices.unitOfMeasure |
string | Indicates the method in which totalBilledUsage is measured. |
deviceResponse. billedUsageResponse. devices.usageSegments |
array | Breaks down the billing and usage details by rating groups. |
deviceResponse. billedUsageResponse. devices.usageAPN |
array | Breaks down the billing and usage details by Access Point Name (APN) for Real-Time Reporting (RTR) customers. |
deviceResponse. billedUsageResponse. devices. usageAPN.apnName |
string | The name of the Access Point (APN). |
deviceResponse. billedUsageResponse. devices. usageSegments.ratingGroup |
string | Breaks down billing and usage based on a contracted rate. |
deviceResponse. billedUsageResponse. devices. usageSegments.ratingGroupDetails |
array | Lists charge and usage details for the billing cycles. |
deviceResponse. billedUsageResponse. devices. apnName.apnNameDetails |
array | Lists charge and usage details for the billing cycles by Access Point Name (APN). |
deviceResponse. billedUsageResponse. devices.(usageSegment or apnName).currentCycleDetails |
array | Lists billing and usage details for the rating group for the specified billing cycle. |
deviceResponse. billedUsageResponse. devices.(usageSegment or apnName). currentCycleDetails.countryCode |
string | Code for the country that the usage and resulting charges are in. |
deviceResponse. billedUsageResponse. devices.(usageSegment or apnName). currentCycleDetails.usage |
integer | Total usage by units of measure in the corresponding country for the billing cycle. |
deviceResponse. billedUsageResponse. devices.(usageSegment or apnName). currentCycleDetails.chargeAmount |
integer | The total dollar amount charged and usage information for the rating group by country code for the current billing cycle. |
usageAPN.apnName.apnNameDetails.qosDetails.qos |
string | The type of data being measured. Currently, this is only "premium data" and "standard data". |
| usageAPN.apnName.apnNameDetails.qosDetails.usage | string | Usage of the data in this category, measured in MB. |
| usageAPN.apnName.apnNameDetails.qosDetails.chargeAmt | string | The cost of the data used in US Dollars. |
| lineStatus | string | The status of the callback response. Valid values include
|
| description | string | If lineStatus is "Failed", provides a short description of the failure. |
| 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. |
| callbackCount | integer | Total number of callback requests. |
| maxCallbackTreshold | integer | Maximum number of callbacks allowed. |
{
"username": "User name requesting the callback",
"password":"user's password",
"requestId":"0998abfc-404b-45ad-ba69-04c137518457",
"deviceResponse":{
"billedUsageResponse":{
"accountName":"0000123456-00001",
"billingCycle":{
"year":2020,
"month":3
},
"devices":[
{
"label":{
"name":"VIN",
"value":"16-digit Vehicle ID number"
},
"ratePlanDescription":"",
"totalBilledAmount":2459319.27,
"totalBilledUsage":409886735,
"unitOfMeasure":"MB",
"lineStatus":"Failed",
"description":"Label not found"
},
{
"deviceId":{
"id":"The Electronic ID of the device",
"kind":"EID",
"oemName" : "the engagement name"
},
"label":{
"name":"VIN",
"value":"16-digit Vehicle ID number"
},
"ratePlanDescription":"Rate Plan Description",
"totalBilledAmount":2459319.27,
"totalBilledUsage":409886735,
"unitOfMeasure":"MB",
"usageSegments":[
{
"ratingGroup":"Group Name",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":27408385,
"chargeAmount":164450.23
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27303937,
"chargeAmount":163823.54
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
}
]
}
},
{
"ratingGroup":"Group Name",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":27408385,
"chargeAmount":164450.23
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27303937,
"chargeAmount":163823.54
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
}
]
}
},
{
"ratingGroup":"Group Name",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":27408385,
"chargeAmount":164450.23
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
},
{
"countryCode":"USA",
"usage":27303937,
"chargeAmount":163823.54
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
}
]
}
}
],
"lineStatus":"Success"
},
{
"deviceId":{
"id":"The Electronic ID of the device",
"kind":"EID",
"oemName" : "the engagement name"
},
"label":{
"name":"VIN",
"value":"16-digit Vehicle ID number"
},
"ratePlanDescription":"Rate Plan Description",
"totalBilledAmount":2459319.27,
"totalBilledUsage":409886735,
"unitOfMeasure":"MB",
"usageSegments":[
{
"ratingGroup":"Group Name",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":27408385,
"chargeAmount":164450.23
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27303937,
"chargeAmount":163823.54
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
}
]
}
},
{
"ratingGroup":"Group Name",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":27408385,
"chargeAmount":164450.23
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27304961,
"chargeAmount":163829.69
},
{
"countryCode":"USA",
"usage":27303937,
"chargeAmount":163823.54
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
}
]
}
},
{
"ratingGroup":"Group Name",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":27408385,
"chargeAmount":164450.23
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
},
{
"countryCode":"USA",
"usage":27303937,
"chargeAmount":163823.54
},
{
"countryCode":"USA",
"usage":27305985,
"chargeAmount":163835.84
}
]
}
}
],
"lineStatus":"Success"
}
],
"pageNumber":1,
"totalPages":1
}
},
"callbackCount":1,
"maxCallbackThreshold":4
}
Note: Instead of usageSegments, Real-Time Reporting (RTR) customers will see usageAPN as below:
{
"username":"user name requesting the callback",
"password":"user's password",
"requestId":"0998abfc-404b-45ad-ba69-04c137518457",
"deviceResponse":{
"billedUsageResponse":{
"accountName":"0000123456-00001",
"billingCycle":{
"year":2020,
"month":3
},
"devices":[
{
"label":{
"name":"VIN",
"value":"16-digit Vehicle ID Number"
},
"ratePlanDescription":"",
"totalBilledAmount":2459.27,
"totalBilledUsage":4098,
"unitOfMeasure":"MB",
"lineStatus":"Failed",
"description":"Label not found"
},
{
"deviceId":{
"id":"The Electronic ID of the device",
"kind":"EID"
},
"label":{
"name":"VIN",
"value":"16-digit Vehicle ID Number"
},
"ratePlanDescription":"Rate Plan Description",
"totalBilledAmount":2459319.27,
"totalBilledUsage":409886735,
"unitOfMeasure":"MB",
"usageAPN":[
{
"apnName":"Access Point Name",
"apnNameDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":3000000,
"chargeAmount":1201.0
}
],
"qosDetails":[
{
"qos":"premium data",
"usage":100,
"chargeAmt":100.0
},
{
"qos":"standard data",
"usage":200,
"chargeAmt":50.0
}
]
}
},
{
"apnName":"Access Point Name",
"apnNameDetails":{
"currentCycleDetails":[
{
"countryCode":"USA",
"usage":3000,
"chargeAmount":12.0
}
],
"qosDetails":[
{
"qos":"premium data",
"usage":100,
"chargeAmt":100.0
},
{
"qos":"standard data",
"usage":200,
"chargeAmt":50.0
}
]
}
},
"lineStatus":"Success"
}
],
"pageNumber":1,
"totalPages":1
}
},
"callbackCount":1,
"maxCallbackThreshold":4
}
Status 400
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}
Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.