Retrieve Billed Usage List:

POST /devices/usage/actions/billedusage/list

Gets billed usage for for either multiple devices or an entire billing account.

Contents

Uses and Requirements

The BilledUsageList API has the following limitations:

  • You can specify only the accountName and get a list of all devices.
  • You can retrieve device billed usage for up to 2,000 devices identified by either deviceId (EID) or label (VIN), but not both.
  • The retrieval of usage and billing is limited to a specified billing cycle, or the most current completed cycle if one is not specified.

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.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/billedusage/list

Resource Path and Query Parameters

None.

Header Parameters

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.

Request Body Parameters

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.
  • EID - 32 digit Electronic ID
  • ICCID - Integrated Circuit Card Identification Number. The 18 to 22 digit idenitfier of the SIM card in the device.
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.

Example Request Body

{
  "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
  }
}

Success Responses

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.

Callback Response Parameters

To receive callbacks, RTR customers must implement a callback listener and register for the DeviceService callbacks.
 
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,
deviceResponse.

billedUsageResponse..

devices.

deviceId.id

string The type and value of the device identifier.
  • EID - 32 digit Electronic ID
  • ICCID - Integrated Circuit Card Identification Number. The 18 to 22 digit idenitfier of the SIM card in the device.

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.
lineStatus string The status of the callback response. Valid values include
  • Success
  • Failed
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.

Example Callback Response

{
   "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"
               },
               "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"
               },
               "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":2459319.27,
               "totalBilledUsage":409886735,
               "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",
               "usageAPNs":[
                  {
                     "apnName":"Access Point Name",
                     "apnNameDetails":{
                        "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
                           }
                        ]
                     }
                  },
                  {
                     "apnName":"Access Point Name",
                     "apnNameDetails":{
                        "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
                           }
                        ]
                     }
                  },
                  {
                     "apnName":"Access Point Name",
                     "apnNameDetails":{
                        "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"
               },
               "label":{
                  "name":"VIN",
                  "value":"16-digit Vehicle ID Number"
               },
               "ratePlanDescription":"Rate Plan Description",
               "totalBilledAmount":2459319.27,
               "totalBilledUsage":409886735,
               "unitOfMeasure":"MB",
               "usageAPNs":[
                  {
                     "apnName":"Access Point Name",
                     "apnNameDetails":{
                        "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
                           }
                        ]
                     }
                  },
                  {
                     "apnName":"Access Point Name",
                     "apnNameDetails":{
                        "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
                           }
                        ]
                     }
                  },
                  {
                     "apnName":"Access Point Name",
                     "apnNameDetails":{
                        "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
}

Failure Responses

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.