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.

# 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/standard-apis/connectivity-management/api-endpoints/device-management/usage-segmentation-label-association/api-reference). 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](/docs/standard-apis/connectivity-management/api-endpoints/device-management/billed-usage-information/billedusageinfo) ## 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: ```json { "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): ```json { "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: ```json { "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: ```json { "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: ```json { "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. |

Verizon 5G Edge API Portal

Retrieve Billed Usage