Standard APIsConnectivity ManagementGuidesUses and Requirements
Retrieve Billed Usage
POST /devices/usage/actions/billedusage
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 (SXM services). 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
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
Using an EID vallue:
{
"accountName": "0000123456-00001",
"label": {
"name": "VIN",
"value": "17-character Vehicle ID"
},
"deviceId": {
"id": "32-digit EID",
"kind": "EID"
},
"billingCycle": {
"year": 2020,
"month": 1
},
"includeQosDetails": "true"
}Or, using the ICCID value (not using a label or requesting QoS details):
{
"accountName": "0000123456-00001",
"deviceIds": [
{
"id": "20-digit ICCID",
"kind": "ICCID"
}
],
"billingCycle": {
"year": 2026,
"month": 3
}
}
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 | An array of label names and label values. Maximum of 2,000 objects are allowed in the array. |
name (required for labels) | string | The label associated with the device, maximum of 20 characters. Provide either label or deviceId values, not both. |
value (required for labels) | string | The label value, maximum 50 characters. |
deviceId (required if not specifying label) | object | An object containg identifiers (kind, id) for a single device. Provide either label or deviceId values, not both. |
kind, id (required for deviceId) | string | The type (kind) and value (id) of the device identifier. EID - Electronic ID. a 32 digit ID of the device. ICCID - Integrated Circuit Card Identification Number. The 20 digit idenitfier of the SIM card in the device. |
| billingCycle (optional) | object | The billing cycle requested for billing information. If the billing cycle is not specified, the most recent billing cycle information is provided. |
year (required for billingCycle) | integer | The year in which the billing cycle occurs. |
month (required for billingCycle) | 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. |
Success Responses
Status 200
Using the EID value:
{
"accountName": "0000123456-00001",
"ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA",
"deviceId": {
"id": "32-digit EID",
"kind": "EID",
"oemName": "OEM name"
},
"billingCycle": {
"year": 2026,
"month": 3
},
"unitOfMeasure": "BYTES",
"totalBilledUsage": 1251482,
"totalBilledAmount": 0.012,
"usageSegments": [
{
"ratingGroup": "SXM SERVICES DATA",
"ratingGroupDetails": {
"currentCycleDetails": [
{
"countryCode": "USA",
"usage": 1251482,
"chargeAmount": 0.012
}
]
}
}
]
}
Using the ICCID value:
{
"accountName": "0000123456-00001",
"ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA",
"deviceId": {
"id": "20-digit ICCID",
"kind": "ICCID",
"oemName": "OEM name"
},
"billingCycle": {
"year": 2026,
"month": 3
},
"unitOfMeasure": "BYTES",
"totalBilledUsage": 1260236,
"totalBilledAmount": 0.012,
"usageSegments": [
{
"ratingGroup": "SXM SERVICES DATA",
"ratingGroupDetails": {
"currentCycleDetails": [
{
"countryCode": "USA",
"usage": 1260236,
"chargeAmount": 0.012
}
]
}
}
]
}
Note: Instead of usageSegments, Real-Time Reporting (RTR) customers will see usageAPN as below:
{
"accountName":"0000123456-00001",
"billingCycle":{
"month":4,
"year":2026
},
"deviceId":{
"id":"32-digit EID",
"kind":"EID"
},
"label":{
"name":"VIN",
"value":"17-character Vehicle ID"
},
"ratePlanDescription":"rate plan used",
"totalBilledAmount":7283.34,
"totalBilledUsage":10485760123,
"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
}
],
"unbilledFromPreviousCycleDetails":[
{
"countryCode":"MEX",
"usage":3000000,
"chargeAmount":288.0,
"chargeDescription":"$0.006 per MB - USA"
}
]
}
}
]
}Response Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName | string | The name of a billing account. An account name is numeric, and must include any leading zeros. |
| billingCycle | object | The billing cycle requested for billing information. |
| month | integer | The number representing the month of the billing cycle. Valid values include integer values between 1 and 12. |
| year | integer | The year in which the billing cycle occurs. |
| deviceId | object | An object containg identifiers (kind, id) for a single device. |
| kind, id | string | The type (kind) and value (id) of the device identifier. EID - Electronic ID. A 32 digit ID of the device. ICCID - Integrated Circuit Card Identification Number. The 20 digit idenitfier of the SIM card in the device. If EID is in the request, EID will be returned. If ICCID is in the request, ICCID will be returned. |
| oemName | string | The engagement name of the manufacturer. Note: This is only returned for usageSegments |
| label | array | An array of label names and label values. Maximum of 2,000 objects are allowed in the array. |
| name | string | The label associated with the device. |
| value | string | 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). Note: Automotive OEM customers now have support for "vanity" APNs. |
| 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. |
| chargeAmount | integer | The total dollar amount charged and usage information for the rating group by country code for the current billing cycle. |
| countryCode | string | Code for the country that the usage and resulting charges are in. |
| usage | integer | Total usage in the corresponding country for the billing cycle. |
| qosDetails | array | An array of QoS objects showing the data ammounts that QoS was applied to and the resulting charges. |
| qos | string | The type of data being measured. Currently, this is only premium data and standard data. |
| usage | string | Usage of the data in this category, measured in MB. |
| chargeAmt | string | The cost of the data used in US Dollars. |
| unbilledFromPreviousCycleDetails | array | An array of objects listing usage and charge information from a previous billing cycle that was not billing until the current billing cycle. |
| chargeAmount | integer | The total dollar amount charged in the rating group in the current billing cycle, but whose usage occurred in a prior cycle. |
| countryCode | string | Code for the country in which the usage and resulting charges occurred in. |
| usage | integer | Total usage from the unbilled cycle. |