POST /devices/usage/actions/billedusageGets billing usage for a customer segment for a specified billing cycle, or the most recent billing 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/list are currently in use by the automotive sector. Please note that these API endpoints are only available on a limited basis.
POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/billedusageNone.
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. |
| 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 of label names and label values | Maximum of 2,000 objects are allowed in the array. |
| label.name required |
Varchar(20) | The label associated with the device. You can only provide either label or deviceId. Not both. |
| label.value required |
Varchar (50) | The label value. |
| deviceId required if not specifying label |
deviceId object | An identifier for a single device. You can only provide either label or deviceId. Not both. |
| deviceId.kind, deviceId.id required if not specifying label* |
string | The type and value of the device identifier.
|
| billingCycle | The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent billing cycle information is provided. | |
| billingCycle.year | integer | The year in which the billing cycle occurs. |
| billingCycle.month | integer | The number representing the month of the billing cycle. Valid values include integers between 1 and 12. |
{
"accountName": "9231221278-99990",
"label": {
"name": "VIN",
"value": "XXUZL54B5YN105457"
},
"deviceId": {
"id": "29183120783667588118432098765864",
"kind": "EID"
},
"billingCycle": {
"year": 2020,
"month": 1
}
}
Status 200
| 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. |
| billingCycle | The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent billing cycle information is provided. | |
| billingCycle.year | integer | The year in which the billing cycle occurs. |
| billingCycle.month | integer | The number representing the month of the billing cycle. Valid values include integer values between 1 and 12. |
| deviceId required if not specifying label |
deviceId object | An identifier for a single device. |
| deviceId.kind, deviceId.id required if not specifying label* |
string | The type and value of the device identifier.
|
| label required if not specifying deviceId |
Array of label names and label values | Maximum of 2,000 objects are allowed in the array. |
| label.name required |
Varchar(20) | The label associated with the device. |
| label.value required |
Varchar (50) | 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). |
| 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. |
| currentCycleDetails.chargeAmount | integer | The total dollar amount charged and usage information for the rating group by country code for the current billing cycle. |
| currentCycleDetails.countryCode | string | Code for the country that the usage and resulting charges are in. |
| currentCycleDetails.usage | integer | Total usage in the corresponding country for the billing cycle. |
| unbilledFromPreviousCycleDetails | array of objects | Lists usage and charge information from a previous billing cycle that was not billing until the current billing cycle. |
| unbilledFromPreviousCycleDetails.chargeAmount | integer | The total dollar amount charged in the rating group in the current billing cycle, but whose usage occurred in a prior cycle. |
| unbilledFromPreviousCycleDetails.countryCode | string | Code for the country in which the usage and resulting charges occurred in. |
| unbilledFromPreviousCycleDetails.usage | integer | Total usage from the unbilled cycle. |
{
"accountName":"9231221278-99990",
"billingCycle":{
"month":1,
"year":2020
},
"deviceId":{
"id":"29183120783667588118432098765864",
"kind":"EID"
},
"label":{
"name":"VIN",
"value":"XXUZL54B5YN105457"
},
"ratePlanDescription":"?XXX?",
"totalBilledAmount":7283.34,
"totalBilledUsage":10485760123,
"unitOfMeasure":"MB",
"usageSegments":[
{
"ratingGroup":"SAMPLE DATA",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"chargeAmount":288,
"countryCode":"US",
"usage":2000000
},
{
"chargeAmount":388,
"countryCode":"CA",
"usage":3000000
}
],
"unbilledFromPreviousCycleDetails":[
{
"chargeAmount":488,
"countryCode":"MX",
"usage":5000000
}
]
}
},
{
"ratingGroup":"SAMPLE DATA 2",
"ratingGroupDetails":{
"currentCycleDetails":[
{
"chargeAmount":588,
"countryCode":"US",
"usage":5000000
},
{
"chargeAmount":688,
"countryCode":"CA",
"usage":6000000
}
],
"unbilledFromPreviousCycleDetails":[
{
"chargeAmount":788,
"countryCode":"MEX",
"usage":7000000
}
]
}
}
]
}
Note: Instead of usageSegments, Real-Time Reporting (RTR) customers will see usageAPN as below:
{
"accountName":"9231221278-99990",
"billingCycle":{
"month":1,
"year":2020
},
"deviceId":{
"id":"29183120783667588118432098765864",
"kind":"EID"
},
"label":{
"name":"VIN",
"value":"XXUZL54B5YN105457"
},
"ratePlanDescription":"?XXX?",
"totalBilledAmount":7283.34,
"totalBilledUsage":10485760123,
"unitOfMeasure":"MB",
"usageAPN":[
{
"apnName":"APN Sample Data",
"apnNameDetails":{
"currentCycleDetails":[
{
"countryCode":"US",
"usage":3000000,
"chargeAmount":288.0,
"chargeDescription":"$0.006 per MB - USA"
}
],
"unbilledFromPreviousCycleDetails":[
{
"countryCode":"MEX",
"usage":3000000,
"chargeAmount":288.0,
"chargeDescription":"$0.006 per MB - USA"
}
]
}
}
]
}
Status 400
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}
Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.