Use this endpoint to retrieve billed data by a user defined rating group or by Access Point Name (APN).
POST https://thingspace.verizon.com/api/m2m/v2/devices/usage/actions/billedNone.
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 parameters. All parameters listed are required unless marked "optional".
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName | string | The numeric name of the account. This value must include all leading zeros. |
| lineLevel | boolean | Indicates if the response detail shows by line or by the overall account.
|
| billingCycle | 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 | object | The billing cycle start 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. |
| 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. |
| 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:
|
| 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:
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 |
{
"accountName": "0000123456-00001",
"lineLevel": true,
"billingCycle": {
"from": {
"year": 2023,
"month": 9
},
"to": {
"year": 2023,
"month": 9
}
}
}
{
"accountName":"0000123456-00001",
"billingCycle":{
"from":{
"year":2022,
"month":7
},
"to":{
"year":2022,
"month":7
}
},
"deviceId":{
"kind":"EID",
"id":"32-digit Electronic ID"
}
}
{
"accountName":"0000123456-00001",
"billingCycle":{
"from":{
"year":2022,
"month":7
},
"to":{
"year":2022,
"month":7
}
},
"label":{
"name":"VIN",
"value":"17-character Vehicle ID Number"
}
}
{
"accountName": "0000123456-00001",
"lineLevel": true,
"billingCycle": {
"from": {
"year": 2023,
"month": 8
},
"to": {
"year": 2023,
"month": 9
}
},
"deviceIds": [
{
"kind": "imei",
"id": "15-digit IMEI"
},
{
"kind": "imei",
"id": "15-digit IMEI"
}
]
}
Status 200
{
"requestId": "be36accb-0a9a-4367-93ab-0af6c4ed256a"
}
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-0a9a-4367-93ab-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":2022,
"month":9
},
"to":{
"year":2023,
"month":2
}
}
}
},
"status":"SUCCESS",
"callbackCount":1,
"maxCallbackThreshold":4
}
Per APN (with Device ID)
{
"requestId":"be36accb-0a9a-4367-93ab-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":2022,
"month":9
},
"to":{
"year":2023,
"month":2
}
}
}
},
"status":"SUCCESS",
"callbackCount":1,
"maxCallbackThreshold":4
}
Per ratingGroup (no Device ID or Label)
{
"requestId":"be36accb-0a9a-4367-93ab-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":2022,
"month":9
},
"to":{
"year":2023,
"month":2
}
}
}
},
"status":"SUCCESS",
"callbackCount":1,
"maxCallbackThreshold":4
}
Per ratingGroup (with Device ID)
{
"requestId":"be36accb-0a9a-4367-93ab-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":2022,
"month":9
},
"to":{
"year":2023,
"month":2
}
}
}
},
"status":"SUCCESS",
"callbackCount":1,
"maxCallbackThreshold":4
}
Per ratingGroup (with Label)
{
"requestId":"be36accb-0a9a-4367-93ab-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":2022,
"month":9
},
"to":{
"year":2023,
"month":2
}
}
}
},
"status":"SUCCESS",
"callbackCount":1,
"maxCallbackThreshold":4
}
Using "lineLevel" with value "true"
{
"requestId": "be36accb-0a9a-4367-93ab-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
}
| 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 | float | The total dollar amount billed for the specified billing cycle. |
| totalBilledUsage |
long | Total usage being billed in units defined by unitOfMeasure. |
| totalUsage |
long | The total amount of usage in the units defined. |
| 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 of objects | The array contains all of the usage information by APN value. Usage by APN is only valid for accounts subscribed to RTR. |
| billedAmount | float | The dollar amount the usage represents. |
| billedUsage | long | Total of usage billed in units defined by unitOfMeasure. |
| totalUsage | 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 | long | Total usage in the units defined in unitOfMeasure |
| totalChargeAmount | float | Dollar value of the usage. |
| totalBilledUsage | 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 | long | Total usage in the units defined in unitOfMeasure. |
| totalChargeAmount | float | Dollar value of the usage. |
| totalBilledUsage | float | Total usage being billed in units defined by unitOfMeasure. |
| usageSegments | array of objects | The array contains all of the usage information by ratingGroup. Details by ratingGroup are only valid for accounts that are not subscribed to RTR. |
| ratingGroup | string | The user defined name of the ratingGroup |
| ratingGroupBilledUsage | long | Total of usage billed for in units defined in unitOfMeasure. |
| ratingGroupTotalUsage | long | Total of usage for the rating group in units defined in unitOfMeasure. |
| ratingGroupBilledAmount | 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 | float | The dollar value of the billed amount. |
| totalBilledUsage | long | Total usage billed for in the units defined in unitOfMeasure |
| totalUsage | 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 | float | The dollar value of the billed amount. |
| totalBilledUsage | long | Total usage being billed in units defined by unitOfMeasure. |
| totalUsage | 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:
|
| callbackCount | integer | The number of callbacks for this request. |
| maxCallbackThreshold | integer | The maximum number of callbacks allowed for this request. |
Status 400
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}