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).

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v2/devices/usage/actions/billed

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

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.

  • true - Details for each line returned
  • false - Details for the account in general returned 
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:

  • 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

Example Request (no Device ID or Label)

{
    "accountName": "0000123456-00001",
    "lineLevel": true,
    "billingCycle": {
        "from": {
            "year": 2023,
            "month": 9
        },
        "to": {
            "year": 2023,
            "month": 9
        }
    }
}

Example Request (with Device ID)

{
   "accountName":"0000123456-00001",
   "billingCycle":{
      "from":{
         "year":2022,
         "month":7
      },
      "to":{
         "year":2022,
         "month":7
      }
   },
   "deviceId":{
      "kind":"EID",
      "id":"32-digit Electronic ID"
   }
}

Example Request (with Label)

{
   "accountName":"0000123456-00001",
   "billingCycle":{
      "from":{
         "year":2022,
         "month":7
      },
      "to":{
         "year":2022,
         "month":7
      }
   },
   "label":{
      "name":"VIN",
      "value":"17-character Vehicle ID Number"
   }
}

Example Request (with Device IDs)

{
    "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"
        }
    ]
}

Success Responses

Status 200

{
"requestId": "be36accb-0a9a-4367-93ab-0af6c4ed256a"
}

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-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
}

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 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:

  • SUCCESS
  • FAILED
callbackCount integer The number of callbacks for this request.
maxCallbackThreshold integer The maximum number of callbacks allowed for this request.

Failure Responses

Status 400

All error messages are returned in this format:

{
      "errorCode": "error code string",
      "errorMessage": "error message string"
    }