Retrieve Billed Usage:

POST /devices/usage/actions/billedusage

Gets billing usage for a customer segment for a specified billing cycle, or the most recent billing cycle if one is not specified.

Contents

Uses and Requirements

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/list are currently in use by the automotive sector.  Please note that these API endpoints are only available on a limited basis.

Request Components

HTTP Request

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

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
required if not specifying deviceId		 Array of label names and label values Maximum of 2,000 objects 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		 deviceId object An identifier for a single device.

You can only provide either label or deviceId. Not both.
deviceId.kind,
deviceId.id
required if not specifying label*		 string The type and value of the device identifier.
  • EID - Electronic ID. a 32 digit ID of the device.
  • ICCID - Integrated Circuit Card Identification Number. The 18 to 22 digit idenitfier of the SIM card in the device.
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.
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.

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
  }
  "includeQosDetails" : "true"
}

Success Responses

Status 200

Response Parameters

Parameter Name Data Type Description
accountName
 string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
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 integer values between 1 and 12.
deviceId
 deviceId object An identifier for a single device.
deviceId.kind,
deviceId.id
 string The type and value of the device identifier.
  • EID - Electronic ID. a 32 digit ID of the device.
  • ICCID - Integrated Circuit Card Identification Number. The 18 to 22 digit idenitfier of the SIM card in the device.
deviceId.oemName
 string

The engagement name of the manufacturer

Note: This is only returned for usageSegments
label
 Array of label names and label values Maximum of 2,000 objects are allowed in the array.
label.name
 Varchar(20) The label associated with the device.
label.value
 Varchar (50) The label value associated with the device.
ratePlanDescription string A description of the rate plan.
totalBilledAmount integer The total dollar amount billed for the specified billing cycle.
totalBilledUsage integer Total of usage in units of measure.
unitOfMeasure string Indicates the method in which totalBilledUsage is measured.
usageSegments array Breaks down the billing and usage details by rating groups.
usageAPN array Breaks down the billing and usage details by Access Point Name (APN) for Real-Time Reporting (RTR) customers.
apnName string The name of the Access Point (APN).
ratingGroup string Breaks down billing and usage based on a contracted rate.
ratingGroupDetails array Lists charge and usage details for the billing cycles.
apnNameDetails array Lists charge and usage details for the billing cycles by Access Point Name (APN).
currentCycleDetails array Lists billing and usage details for the rating group for the specified billing cycle.
currentCycleDetails.chargeAmount integer The total dollar amount charged and usage information for the rating group by country code for the current billing cycle.
currentCycleDetails.countryCode string Code for the country that the usage and resulting charges are in.
currentCycleDetails.usage integer Total usage in the corresponding country for the 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.
unbilledFromPreviousCycleDetails array of objects Lists usage and charge information from a previous billing cycle that was not billing until the current billing cycle.
unbilledFromPreviousCycleDetails.chargeAmount integer The total dollar amount charged in the rating group in the current billing cycle, but whose usage occurred in a prior cycle.
unbilledFromPreviousCycleDetails.countryCode string Code for the country in which the usage and resulting charges occurred in.
unbilledFromPreviousCycleDetails.usage integer Total usage from the unbilled cycle.

Example Success Response

{
   "accountName":"9231221278-99990",
   "billingCycle":{
      "month":1,
      "year":2020
   },
   "deviceId":{
      "id":"29183120783667588118432098765864",
      "kind":"EID",
      "oemName" : "the engagement name"
   },
   "label":{
      "name":"VIN",
      "value":"XXUZL54B5YN105457"
   },
   "ratePlanDescription":"?XXX?",
   "totalBilledAmount":7283.34,
   "totalBilledUsage":10485760123,
   "unitOfMeasure":"MB",
   "usageSegments":[
      {
         "ratingGroup":"SAMPLE DATA",
         "ratingGroupDetails":{
            "currentCycleDetails":[
               {
                  "chargeAmount":288,
                  "countryCode":"US",
                  "usage":2000000
               },
               {
                  "chargeAmount":388,
                  "countryCode":"CA",
                  "usage":3000000
               }
            ],
            "unbilledFromPreviousCycleDetails":[
               {
                  "chargeAmount":488,
                  "countryCode":"MX",
                  "usage":5000000
               }
            ]
         }
      },
      {
         "ratingGroup":"SAMPLE DATA 2",
         "ratingGroupDetails":{
            "currentCycleDetails":[
               {
                  "chargeAmount":588,
                  "countryCode":"US",
                  "usage":5000000
               },
               {
                  "chargeAmount":688,
                  "countryCode":"CA",
                  "usage":6000000
               }
            ],
            "unbilledFromPreviousCycleDetails":[
               {
                  "chargeAmount":788,
                  "countryCode":"MEX",
                  "usage":7000000
               }
            ]
         }
      }
   ]
}

Note: Instead of usageSegments, Real-Time Reporting (RTR) customers will see usageAPN as below:

{
   "accountName":"9231221278-99990",
   "billingCycle":{
      "month":1,
      "year":2020
   },
   "deviceId":{
      "id":"29183120783667588118432098765864",
      "kind":"EID"
   },
   "label":{
      "name":"VIN",
      "value":"XXUZL54B5YN105457"
   },
   "ratePlanDescription":"?XXX?",
   "totalBilledAmount":7283.34,
   "totalBilledUsage":10485760123,
   "unitOfMeasure":"MB",
   "usageAPN":[
   {
      "apnName":"vzwb2binternet",
      "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
            }
         ],
            "unbilledFromPreviousCycleDetails":[
               {
                  "countryCode":"MEX",
                  "usage":3000000,
                  "chargeAmount":288.0,
                  "chargeDescription":"$0.006 per MB - USA"
               }
            ]
         }
      }
   ]
}

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.