Bulk Retrieve Billed Usage

Retrieve Billed Usage List:
POST /devices/usage/actions/billedusage/list

Gets customer segment billing usage for an account number, or for a list of devices or labels.

Contents

Uses and Requirements

The BilledUsageList API has the following limitations: • You can specify only the accountName and get a list of all devices. • You can only specify up to 2,000 deviceIds or labels in the request. • The retrieval of usage and billing is limited to a specified billing cycle, or the most current completed cycle if one is not specified.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/billedusage/list

Resource Path and Query Parameters

None.

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 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 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.
  • EID - decimal, 20 digits
billingCycle The billing cycle for which you want billing information. If you do not specify the billing cycle, the most recent completed 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.

Example Request Body

{
  "accountName": "0342330389-00001",    
  "labels": [                           
    {                                   
      "name": "VIN",
      "value": "1N4AL3AP2DC276747"
    },
    {
      "name": "VIN",
      "value": "2N7DL3ZP2DF236943"
    }
  ],
  "deviceIds": [
    {
      "kind": "EID",
      "id": "8991101200003204514"
    },
    {
      "kind": "EID",
      "id": "8914139078080784259"
    }
  ],
  "billingCycle": {                     
    "year": 2020,                       
    "month": 3
  }
}

Success Responses

Status 200

Parameter Name Data Type Description
requestId
required
string A unique string that associates the request with the results that are sent via a callback message.

Callback Request Parameters

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
required
string A unique string that associates the request with the results that are sent via a callback message.
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 completed 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.
  • EID - decimal, 20 digits
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.
ratingGroup string Breaks down billing and usage based on a contracted rate.
ratingGroupDetails array Lists charge and usage details for the billing cycles.
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.chargeDescription string Lists the details of the charges per unit of measure for the rate group.
currentCycleDetails.countryCode string Code for the country that the usage and resulting charges are in.
currentCycleDetails.usage integer Total usage by units of measure 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 by units of measure from the unbilled cycle.
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.
status string The status of the callback response. Valid values include
  • Success
  • Failed
callbackCount integer Total number of callback requests.
maxCallbackTreshold integer Maximum number of callbacks allowed.

Example Callback Request

{
  "username": "foo",
  "password": "bar",
  "requestId": "e019e704-cf20-4774-b9ac-46f2edef0eb0",
  "deviceResponse": {
    "billedUsageResponse": {
      "accountName": "0342330389-00001",
      "billingCycle": {
        "month": 3,
        "year": 2020
      },
      "devices": [
        {
          "deviceId": {
            "id": "8991101200003204514",
            "kind": "EID"
          },
          "label": {
            "name": "VIN",
            "value": "1N4AL3AP2DC276747"
          },
          "ratePlanDescription": "CUSTOM 4G M2M PAYGO DATA",
          "totalBilledAmount": 7283.34,
          "totalBilledUsage": 10485760123,
          "unitOfMeasure": "MB",
          "usageSegments": [
            {
              "ratingGroup": "SXM STRMG AUDIO DATA",
              "ratingGroupDetails": {
                "currentCycleDetails": [
                  {
                    "chargeAmount": 288,
                    "countryCode": "USA",
                    "usage": 2000000
                  },
                  {
                    "chargeAmount": 388,
                    "countryCode": "CAN",
                    "usage": 3000000
                  }
                ],
                "unbilledFromPreviousCycleDetails": [
                  {
                    "chargeAmount": 488,
                    "countryCode": "MEX",
                    "usage": 5000000
                  }
                ]
              }
            },
            {
              "ratingGroup": "SXM ACCT MGMT DATA",
              "ratingGroupDetails": {
                "currentCycleDetails": [
                  {
                    "chargeAmount": 588,
                    "countryCode": "USA",
                    "usage": 5000000
                  },
                  {
                    "chargeAmount": 688,
                    "countryCode": "CAN",
                    "usage": 6000000
                  }
                ],
                "unbilledFromPreviousCycleDetails": [
                  {
                    "chargeAmount": 788,
                    "countryCode": "MEX",
                    "usage": 7000000
                  }
                ]
              }
            }
          ]
        }
      ],
      "pageNumber": 3,
      "totalPages": 7
    }
  },
  "status": "Success",
  "callbackCount": 1,
  "maxCallbackThreshold": 4
}

Sample Callback Response

Status 200

Failure Responses

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.