## Retrieve Billed Usage List ### `POST /devices/usage/actions/billedusage/list` 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](/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 the EID value: ```json { "accountName": "0000123456-00001", "labels": [ { "name": "VIN", "value": "17-digit Vehicle ID number" }, { "name": "VIN", "value": "17-digit Vehicle ID number" } ], "deviceIds": [ { "kind": "EID", "id": "32-digit EID" }, { "kind": "EID", "id": "32-digit EID" } ], "billingCycle": { "year": 2020, "month": 3 }, "includeQosDetails": "true" } ``` Using the ICCID value (without labels or QoS details): ```json { "accountName": "0000123456-00001", "deviceIds": [ { "id": "20-digit ICCID", "kind": "ICCID" }, { "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. <br> **EID** - Electronic ID. a 32 digit ID of the device. <br> **ICCID** - Integrated Circuit Card Identification Number. The 20 digit idenitfier of the SIM card in the device. <br> **Note:** The request cannot contain both EID and ICCID values. Requests sent with both will error out.| | **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. <br> **Note:** This is for RTR accounts only. | ## Success Response **Status 200** ```json { "requestId":"0998abfc-eeee-ffff-gggg-04c137518457" } ``` ## Success Parameters | Parameter Name | Data Type | Description | |--------------|-------------|---------------------------------| | **requestId** | string | A unique string (UUID) that associates the request with the results that are sent via a callback message. | ## Error Scenario If the request body has both an ICCID value and an EID value, like this: ```json { "accountName": "0000123456-00001", "deviceIds": [ { "id": "32-digit EID", "kind": "EID" }, { "id": "20-digit ICCID", "kind": "ICCID" } ], "billingCycle": { "year": 2026, "month": 3 } } ``` The request will fail with the following error output: ```json { "accountName": "0000123456-00001", "fault": { "code": "PROCESSING_EXCEPTION", "message": "All device identifiers in the request must have the same kind." }, "requestId": "0998abfc-eeee-ffff-gggg-04c137518457", "status": "Failed" } ``` ## Callback Response Using the EID value ```json { "callbackCount": 1, "deviceResponse": { "billedUsageResponse": { "accountName": "0000123456-00001", "billingCycle": { "month": 3, "year": 2026 }, "devices": [ { "deviceId": { "id": "32-digit EID", "kind": "EID", "oemName": "OEM name" }, "lineStatus": "Success", "ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA", "totalBilledAmount": 0.024, "totalBilledUsage": 3568411, "unitOfMeasure": "BYTES", "usageSegments": [ { "ratingGroup": "SXM SERVICES DATA", "ratingGroupDetails": { "currentCycleDetails": [ { "chargeAmount": 0.024, "countryCode": "USA", "usage": 3568411 } ] } } ] }, { "deviceId": { "id": "32-digit EID", "kind": "EID", "oemName": "OEM name" }, "lineStatus": "Success", "ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA", "totalBilledAmount": 0.006, "totalBilledUsage": 232752, "unitOfMeasure": "BYTES", "usageSegments": [ { "ratingGroup": "SXM SERVICES DATA", "ratingGroupDetails": { "currentCycleDetails": [ { "chargeAmount": 0.006, "countryCode": "USA", "usage": 232752 } ] } } ] } ], "pageNumber": 1, "totalPages": 870 } }, "maxCallbackThreshold": 4, "requestId": "0998abfc-eeee-ffff-gggg-04c137518457", "status": "Success" } ``` Using the ICCID value: ```json { "callbackCount": 1, "deviceResponse": { "billedUsageResponse": { "accountName": "0000123456-00001", "billingCycle": { "month": 3, "year": 2026 }, "devices": [ { "deviceId": { "id": "20-digit ICCID", "kind": "ICCID", "oemName": "OEM name" }, "lineStatus": "Success", "ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA", "totalBilledAmount": 0.024, "totalBilledUsage": 3568411, "unitOfMeasure": "BYTES", "usageSegments": [ { "ratingGroup": "SXM SERVICES DATA", "ratingGroupDetails": { "currentCycleDetails": [ { "chargeAmount": 0.024, "countryCode": "USA", "usage": 3568411 } ] } } ] }, { "deviceId": { "id": "20-digit ICCID", "kind": "ICCID", "oemName": "OEM name" }, "lineStatus": "Success", "ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA", "totalBilledAmount": 0.006, "totalBilledUsage": 232752, "unitOfMeasure": "BYTES", "usageSegments": [ { "ratingGroup": "SXM SERVICES DATA", "ratingGroupDetails": { "currentCycleDetails": [ { "chargeAmount": 0.006, "countryCode": "USA", "usage": 232752 } ] } } ] } ], "pageNumber": 1, "totalPages": 870 } }, "maxCallbackThreshold": 4, "requestId": "0998abfc-eeee-ffff-gggg-04c137518457", "status": "Success" } ``` **Note:** Instead of `usageSegments`, Real-Time Reporting (RTR) customers will see `usageAPN` as below: ```json { "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 } ``` ## 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. | | **billedUsageResponse** | object | Contains the account information and the billing period being queried. | | **accountName** | string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. | | **billingCycle** | object | The billing cycle requested for billing information. | | **year** | integer | The year in which the billing cycle occurs. | | **month** | integer | The number representing the month of the billing cycle. Valid values include integer values between 1 and 12. | | **devices** | array | An array of all the devices responding in the callback. | | **deviceId** | object | An identifier for a single device. | | **kind, id** | string | The type (`kind`) and value (`id`) of the device identifier. <br> **Note:** If an EID value is in the request an EID value will be in the response and if an ICCID value is in the request an ICCID value will be returned in the response. If an account level request is made, potentially both EID and ICCID values will be returned in the response. | | **oemName** | string | The engagement name of the manufacturer. <br> **Note:** This is only returned for `usageSegments` | | **label** | array | label name and value objects. | | **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 Access Point Name (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. | | **countryCode** | string | Code for the country that the usage and resulting charges are in. | | **usage** | integer | Total usage by units of measure in the corresponding country for the billing cycle. | | **chargeAmount** | integer | The total dollar amount charged and usage information for the rating group by country code for the current 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.| | **lineStatus** | string | The status of the callback response. Valid values include: **Success** and **Failed**. | | **description** | string | If `lineStatus` is **Failed**, this field 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. |