Specialized APIsAutomotive OEMAPI Reference
Billing Data Summary
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.
| 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)
{
"accountName": "0000123456-00001",
"lineLevel": true,
"billingCycle": {
"from": {
"year": 2024,
"month": 8
},
"to": {
"year": 2024,
"month": 9
}
}
}Example Request (with Device ID)
{
"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)
{
"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)
{
"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
{
"requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a"
}Failure Responses
All error messages are returned in this format:
{
"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):
{
"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):
{
"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):
{
"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):
{
"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):
{
"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"
{
"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. |