# Billing Data Summary by APN or RatingGroup ### `POST /v2/devices/usage/actions/billed` Use this endpoint to retrieve billed data by a user defined rating group or by Access Point Name (APN). ## Header Parameters The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit [Getting Started](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/getting-started/introduction-to-the-connectivity-management-api). |Parameter Name|Data Type|Description| |-----|-----|-----| | **Authorization** *(required)* | string | HTTP Authorization request header containing a valid Bearer token: `Authorization: Bearer {token}` | | **VZ-M2M-Token** *(required)* | string | A valid session token returned by a Connectivity Management `POST /session/login` request. | | **Content-Type** *(required)* | string | Must be `application/json`. | ## HTTP Request ### `POST https://thingspace.verizon.com/api/m2m/v2/devices/usage/actions/billed` ## Request Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **accountName** *(required)* | string | The numeric name of the account. This value must include all leading zeros. | | **lineLevel** *(required)*| boolean | Indicates if the response detail shows by line or by the overall account. **true** - Details for each line returned. **false** - Details for the account in general returned. | | **billingCycle** *(required)* | object | The billing cycle object contains the starting (from) year, month and ending (to) year, month of the cycle being queried. **Note:** For all data in the same month, the same month value is used as the start and end month. "from" and "to" are inclusive. | | **from** *(required)* | object | The billing cycle start date. | | **year** *(required)* | integer | The 4 digit year of the billing cycle being queried. | | **month** *(required)* | integer | The numeric month value, 1 through 12, of the billing cycle being queried. 1 is January, 2 is February, etc. | | **to** *(required)* | object | The billing cycle end date. | | **year** *(required)* | integer | The 4 digit year of the billing cycle being queried. | | **month** *(required)* | integer | The numeric month value, 1 through 12, of the billing cycle being queried. 1 is January, 2 is February, etc. | | **deviceId** *(optional)* | object | The Device ID object contains an ID value as well as a definition (`kind`) of what the type of ID value is listed. Valid values are: **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. | | **deviceIds** *(optional)* | object | The Device IDs (multiple) object contains an ID value as well as a definition (`kind`) of what the type of ID value is listed. Valid values are: **IMEI** - 15-digit International Mobile Equipment Identifier. **Note:** `deviceId` and `deviceIds` **CANNOT** be in the same request. If `deviceIds` is used, `lineLevel` MUST be set to "**true**". | | **label** *(optional)* | object | The `label` object contains a user defined name and value. The example uses Vehicle ID Number (**VIN**), a 17-character alphanumeric value. **Note:** labels are not valid for APN. | ## Request Body Example Request (no Device ID or Label) ```json { "accountName": "0000123456-00001", "lineLevel": true, "billingCycle": { "from": { "year": 2024, "month": 8 }, "to": { "year": 2024, "month": 9 } } } ``` Example Request (with Device ID) ```json { "accountName":"0000123456-00001", "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } }, "deviceId":{ "kind":"EID", "id":"32-digit Electronic ID" } } ``` Example Request (with Label) ```json { "accountName":"0000123456-00001", "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } }, "label":{ "name":"VIN", "value":"17-character Vehicle ID Number" } } ``` Example Request (with Device IDs) ```json { "accountName": "0000123456-00001", "lineLevel": true, "billingCycle": { "from": { "year": 2024, "month": 8 }, "to": { "year": 2024, "month": 9 } }, "deviceIds": [ { "kind": "imei", "id": "15-digit IMEI" }, { "kind": "imei", "id": "15-digit IMEI" } ] } ``` ## Success Responses **Status 200** ```json { "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a" } ``` ## Failure Responses All error messages are returned in this format: ```json { "errorCode": "error code string", "errorMessage": "error message string" } ``` ## Callback Examples Accounts that are subscribed to Real-time Rating (RTR) will see `usageApns`. Accounts that are not subscribed to RTR will see `ratingGroups`. Per APN (no Device ID or Label): ```json { "requestId":"be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse":{ "billingUsageSummary":{ "accountName":"0000123456-00001", "totalBilledAmount":392.5, "totalBilledUsage":4080000, "totalUsage":408000, "unitOfMeasure":"BYTES", "usageApns":[ { "billedAmount":200.5, "billedUsage":2160000, "totalUsage":2160000, "name":"name of the APN reporting", "pageNumber":0, "apnDetails":{ "totalDelayedUsageDetails":[ { "countryCode":"US", "totalChargeAmount":179.5, "totalBilledUsage":179.5, "totalUsage":1950000 } ], "totalUsageDetails":[ { "countryCode":"US", "totalChargeAmount":21.0, "totalBilledUsage":21.0, "totalUsage":210000 } ] } }, { "billedAmount":192.0, "billedUsage":1920000, "name":"name of the APN reporting", "pageNumber":0, "apnDetails":{ "totalDelayedUsageDetails":[ { "countryCode":"US", "totalChargeAmount":0.0, "totalBilledUsage":179.5, "totalUsage":1795000 } ], "totalUsageDetails":[ { "countryCode":"US", "totalChargeAmount":192.0, "totalBilledUsage":179.5 "totalUsage":1795000 } ] } } ], "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } } } }, "status":"SUCCESS", "callbackCount":1, "maxCallbackThreshold":4 } ``` Per APN (with Device ID): ```json { "requestId":"be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse":{ "billingUsageSummary":{ "accountName":"0000123456-00001", "totalBilledAmount":392.5, "totalBilledUsage":4080000, "totalUsage":408000, "unitOfMeasure":"BYTES", "deviceIdentifier": { "id": "22-digit ICCID", "kind": "ICCID" "usageApns":[ { "billedAmount":200.5, "billedUsage":2160000, "totalUsage":2160000, "name":"name of the APN reporting", "pageNumber":0, "apnDetails":{ "totalDelayedUsageDetails":[ { "countryCode":"US", "totalChargeAmount":179.5, "totalBilledUsage":179.5, "totalUsage":1950000 } ], "totalUsageDetails":[ { "countryCode":"US", "totalChargeAmount":21.0, "totalBilledUsage":21.0, "totalUsage":210000 } ] } }, { "billedAmount":192.0, "billedUsage":1920000, "name":"name of the APN reporting", "pageNumber":0, "apnDetails":{ "totalDelayedUsageDetails":[ { "countryCode":"US", "totalChargeAmount":0.0, "totalBilledUsage":179.5, "totalUsage":1795000 } ], "totalUsageDetails":[ { "countryCode":"US", "totalChargeAmount":192.0, "totalBilledUsage":179.5 "totalUsage":1795000 } ] } } ], "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } } } }, "status":"SUCCESS", "callbackCount":1, "maxCallbackThreshold":4 } ``` Per `ratingGroup` (no Device ID or Label): ```json { "requestId":"be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse":{ "billingUsageSummary":{ "accountName":"0000123456-00001", "totalBilledAmount":3821.3, "totalBilledUsage":30700000, "totalUsage":30700000, "unitOfMeasure": "BYTES", "usageSegments":[ { "ratingGroup":"user defined group name", "ratingGroupBilledAmount":3821.3, "ratingGroupBilledUsage":30700000, "ratingGroupTotalUsage":30700000, "ratingGroupDetails":{ "totalDelayedUsageDetails":[ { "chargeAmount":600.5, "totalBilledUsage":5500000, "totalUsage":5500000, "countryCode":"MX" }, { "chargeAmount":1300.0, "totalBilledUsage":10000000, "totalUsage":5500000, "countryCode":"US" } ], "totalUsageDetails":[ { "chargeAmount":610.4, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"CA" }, { "chargeAmount":710.4, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"MX" }, { "chargeAmount":600.0, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"US" } ] } } ], "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } } } }, "status":"SUCCESS", "callbackCount":1, "maxCallbackThreshold":4 } ``` Per `ratingGroup` (with Device ID): ```json { "requestId":"be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse":{ "billingUsageSummary":{ "accountName":"0000123456-00001", "totalBilledAmount":3821.3, "totalBilledUsage":30700000, "totalUsage":30700000, "unitOfMeasure": "BYTES", "deviceIdentifier": { "id": "32-digit Electronic ID", "kind": "EID" "usageSegments":[ { "ratingGroup":"user defined group name", "ratingGroupBilledAmount":3821.3, "ratingGroupBilledUsage":30700000, "ratingGroupTotalUsage":30700000, "ratingGroupDetails":{ "totalDelayedUsageDetails":[ { "chargeAmount":600.5, "totalBilledUsage":5500000, "totalUsage":5500000, "countryCode":"MX" }, { "chargeAmount":1300.0, "totalBilledUsage":10000000, "totalUsage":5500000, "countryCode":"US" } ], "totalUsageDetails":[ { "chargeAmount":610.4, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"CA" }, { "chargeAmount":710.4, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"MX" }, { "chargeAmount":600.0, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"US" } ] } } ], "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } } } }, "status":"SUCCESS", "callbackCount":1, "maxCallbackThreshold":4 } ``` Per `ratingGroup` (with `label`): ```json { "requestId":"be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse":{ "billingUsageSummary":{ "accountName":"0000123456-00001", "totalBilledAmount":3821.3, "totalBilledUsage":30700000, "totalUsage":30700000, "unitOfMeasure": "BYTES", "label": { "name": "VIN", "value": "17-character Vehicle ID Number" "usageSegments":[ { "ratingGroup":"user defined group name", "ratingGroupBilledAmount":3821.3, "ratingGroupBilledUsage":30700000, "ratingGroupTotalUsage":30700000, "ratingGroupDetails":{ "totalDelayedUsageDetails":[ { "chargeAmount":600.5, "totalBilledUsage":5500000, "totalUsage":5500000, "countryCode":"MX" }, { "chargeAmount":1300.0, "totalBilledUsage":10000000, "totalUsage":5500000, "countryCode":"US" } ], "totalUsageDetails":[ { "chargeAmount":610.4, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"CA" }, { "chargeAmount":710.4, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"MX" }, { "chargeAmount":600.0, "totalBilledUsage":5100000, "totalUsage" :5500000, "countryCode":"US" } ] } } ], "billingCycle":{ "from":{ "year":2024, "month":8 }, "to":{ "year":2024, "month":9 } } } }, "status":"SUCCESS", "callbackCount":1, "maxCallbackThreshold":4 } ``` Using `lineLevel` with value "**true**" ```json { "requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a", "deviceResponse": { "billingUsageSummary": { "accountName": "0000123456-00001", "totalBilledAmount": 1993.4, "totalBilledUsage": 59935, "totalUsage": 72378, "unitOfMeasure": "BYTES", "billingCycle": { "from": { "year": 2023, "month": 8 }, "to": { "year": 2023, "month": 9 } }, "pageNumber": 1, "totalPages": 1, "devices": [ { "deviceIdentifier": { "id": "15-digit IMEI", "kind": "imei" }, "totalBilledAmount": 1993.0, "totalBilledUsage": 59935, "totalUsage": 72378, "usageApns": [ { "billedAmount": 1993.4, "billedUsage": 59935, "name": "APN name", "totalUsage": 72378, "apnDetails": { "totalUsageDetails": [ { "countryCode": "USA", "totalChargeAmount": 1993.4, "totalBilledUsage": 59935, "totalUsage": 72378 } ] } } ] } ] } }, "status": "SUCCESS", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` ## Callback Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **requestId** | string | The system generated ID of the callback request. | | **deviceResponse** | object | The response back from an active device. | | **billingUsageSummary** | object | The complete summary of billed usage in the account. | | **accountName** | string | The name of a billing account. An account name is usually numeric, and must include any leading zeros. | | **totalBilledAmount** | number (float) | The total dollar amount billed for the specified billing cycle. | | **totalBilledUsage** | integer (long) | Total usage being billed in units defined by unitOfMeasure. | | **totalUsage** | integer (long) | The total amount of usage in the units defined in `unitOfMeasure`. | | **unitOfMeasure** | string | The unit of measurement for values displayed. | | **label** | object | A user defined label containing a name and a value. Labels are only displayed if the request contained one or more labels. **Note:** labels are not valid for APN. | | **deviceIdentifier** | object | Either the `kind` **EID** or **ICCID** and its ID value. Device IDs are only displayed if the request contained a device ID. | | **usageAPNs** | array | The array contains all of the usage information by APN value. **Note:** Usage by APN is only valid for accounts subscribed to RTR. | | **billedAmount** | number (float) | The dollar amount the usage represents. | | **billedUsage** | integer (long) | Total of usage billed in units defined by `unitOfMeasure`. | | **totalUsage** | integer (long) | Total of usage in units defined by `unitOfMeasure`. | | **name** | string | The name of the Access Point (APN) reporting. | | **pageNumber** | integer | The number of pages returned. **Note:** This value will only be displayed for APN requests not using a device ID. | | **apnDetails** | object | Breaks down the billing and usage details by current and delayed usage. | | **totalDelayedUsageDetails** | array | Usage captured but not billed in this cycle. | | **countryCode** | string | 2-letter country code of where the usage occured. Conforms to ISO-3166. | | **totalUsage** | integer (long) | Total usage in the units defined in `unitOfMeasure`. | | **totalChargeAmount** | number (float) | Dollar value of the usage. | | **totalBilledUsage** | number (float) | Total usage being billed in units defined by `unitOfMeasure`. | | **totalUsageDetails** | array | Current usage details. | | **countryCode** | string | 2-letter country code of where the usage occured. Conforms to ISO-3166. | | **totalUsage** | integer (long) | Total usage in the units defined in `unitOfMeasure`. | | **totalChargeAmount** | number (float) | Dollar value of the usage. | | **totalBilledUsage** | number (float) | Total usage being billed in units defined by `unitOfMeasure`. | | **usageSegments** | array | The array contains all of the usage information by `ratingGroup`. **Note:** Details by `ratingGroup` are only valid for accounts that are not subscribed to RTR. | | **ratingGroup** | string | The user defined name of the `ratingGroup`. | | **ratingGroupBilledUsage** | integer (long) | Total of usage billed for in units defined in `unitOfMeasure`. | | **ratingGroupTotalUsage** | integer (long) | Total of usage for the rating group in units defined in `unitOfMeasure`. | | **ratingGroupBilledAmount** | number (float) | Dollar value of the usage. | | **ratingGroupDetails** | object | Breaks down the billing and usage details by current and delayed usage. | | **totalDelayedUsageDetails** | array | Usage captured but not billed in this cycle. | | **chargeAmount** | number (float) | The dollar value of the billed amount. | | **totalBilledUsage** | integer (long) | Total usage billed for in the units defined in `unitOfMeasure`. | | **totalUsage** | integer (long) | Total usage recorded in the units defined in `unitOfMeasure`. | | **countryCode** | string | 2-letter country code of where the usage occured. Conforms to ISO-3166. | | **totalUsageDetails** | array | Current usage details. | | **chargeAmount** | number (float) | The dollar value of the billed amount. | | **totalBilledUsage** | integer (long) | Total usage being billed in units defined by `unitOfMeasure`. | | **totalUsage** | integer (long) | Total usage recorded in the units defined in `unitOfMeasure`. | | **countryCode** | string | 2-letter country code of where the usage occured. Conforms to ISO-3166. | | **month** | integer | The numeric month value, 1 through 12, of the billing cycle being queried. 1 is January, 2 is February, etc. | | **to** | object | The billing cycle end date. | | **year** | integer | The 4 digit year of the billing cycle being queried. | | **month** | integer | The numeric month value, 1 through 12, of the billing cycle being queried. 1 is January, 2 is February, etc. | | **status** | string | Indicates the status of the callback. Valid values are: **SUCCESS** or **FAILED**. | | **callbackCount** | integer | The number of callbacks returned for this request. | | **maxCallbackThreshold** | integer | The maximum number of callbacks allowed for this request. |