Get Usage by Rate Plan

Description

Returns usage information associated with a single rate plan during a specified billing cycle. By default, the function returns cycle-to-date data, SMS, and voice usage for all devices using the current version of the rate plan. However, you can request a particular usage type, a past billing cycle, or a different rate plan version. A user can request information about rate plans associated with accounts they have access to.

Shared Rate Plans Not Supported. Be aware that you cannot request usage information for a shared rate plan.

Resource URL

GET rws/api/v{apiVersion}/usages

Request Parameters

The rate plan name and API version number are required. All other parameters are optional.

Request Parameters and Description
Parameter	Description
apiVersion	The version number for this API. The current version for all functions is 1.
ratePlanName	The name of the desired rate plan.
cycleStartDate	(Optional) The start date of a desired billing cycle. The format is yyyy-MM-dd. The function returns cycle-to-date usage information if this parameter is not used. You can get the cycle start day for your account using the Get Device Usage by Zone API (cycleStartDate response parameter). Be aware the date format for the cycleStartDate response parameter in Get Device Usage by Zone is different from the format for the cycleStartDate request parameter in Get Usage by Rate Plan.
usageType	(Optional) The type of usage information the function should return. Options are: DATA, SMS, and VOICE. You can specify only one type. However, the function returns all types of usage information if this parameter is not present.
ratePlanVersion	(Optional) The desired rate plan version. It's possible for two versions of the same rate plan to be active during the same billing cycle. This parameter allows you to specify which version you want to use. The function returns information for the most recent version of the rate plan if this parameter is not present.
pageNumber	(Optional) Specifies the number of response pages to return. This value defaults to 1. See Pagination.
pageSize	(Optional) Specifies the number of records returned in each response page. The maximum value is 50. The value defaults to 50. See Pagination.

Response Parameters

The function returns an array of zones, where each zone contains an array of devices. For each device, there are total usage numbers for the requested usage types. A device may have usage in more than one zone and, as a result, may appear multiple times in the response.

Return Values and Description
Return Value	Description
accountId	The ID of the account using the rate plan.
accountName	The name of the account using the rate plan.
ratePlanName	The name of the rate plan.
ratePlanVersion	The version of the rate plan.
pageNumber	An integer specifying the number of the current response page.
lastPage	A true or false value indicating whether the current response page is the last in the series.
Zones
zones	An array of zones used in the rate plan.
zone	The name of a zone.
Devices
devices	An array of devices that used network services in the zone. The following information is returned for each device.
deviceId	The ICCID for the device. This field does not contain the Device ID found on the Device Details page. The ICCID is a unique identifier for a device in Control Center. Device ID is an optional identifier that the account or customer can give to each device.
usage	A label that indicates the usage fields for the current device. The function returns all usage information unless you specify a particular usage type. If you request one type of usage, the function returns all usage fields, but inserts zero values in the non-requested usage fields, regardless of the actual values.
dataUsage	The volume of data (in bytes) used by the device during the time period (cycle to date or a particular billing cycle). If you request a different usage type, the value in this field will be zero, regardless of the actual value.
smsMOUsage	The number of messages sent by the device during the time period (cycle to date or a particular billing cycle). If you request a different usage type, the value in this field will be zero, regardless of the actual value.
smsMTUsage	The number of messages received by the device during the time period (cycle to date or a particular billing cycle). If you request a different usage type, the value in this field will be zero, regardless of the actual value.
voiceMOUsage	The number of seconds a device used for outbound calls during the time period (cycle to date or a particular billing cycle). If you request a different usage type, the value in this field will be zero, regardless of the actual value.
voiceMTUsage	The number of seconds a device used for inbound calls during the time period (cycle to date or a particular billing cycle). If you request a different usage type, the value in this field will be zero, regardless of the actual value.

Request Example

Make sure to use your own user credentials. See Authentication for information about creating an authorization header.

json

Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>"https://rws-jpotest.jasper.com/rws/api/v1/usages?ratePlan=Monthly-Flexible-Pool&pageNumber=1&pageSize=50"

Response Example

markup

Copy{
   "accountId": 100477039,
   "accountName": "Acme Corp",
   "ratePlanName": "Monthly-Flexible-Pool",
   "ratePlanVersion": 1,
   "zones": [
   {
      "zone": "Zone A",
         "devices": [
         {
            "deviceId": "8988209000000000723",
            "usage": {
               "dataUsage": 54765,
               "smsMOUsage": 37,
               "smsMTUsage": 42,
               "voiceMOUsage": 0,
               "voiceMTUsage": 0
               }
             },
         {
            "deviceId": "8988209000000000747",
            "usage": {
               "dataUsage": 23456,
               "smsMOUsage": 15,
               "smsMTUsage": 11,
               "voiceMOUsage": 0,
               "voiceMTUsage": 0
               }
            }
         ]
      "zone": "Zone B",
         "devices": [
         {
            "deviceId": "8988209000000000859",
            "usage": {
               "dataUsage": 94480,
               "smsMOUsage": 0,
               "smsMTUsage": 0,
               "voiceMOUsage": 900,
               "voiceMTUsage": 0
               }
            }
         ]
      }
   ]
   "pageNumber": 2,
   "lastPage": true
}

Errors

Error Codes, HTTP Codes, and Descriptions
Error Code	HTTP Code	Error Message
10000001	401	Invalid credentials. Description: Control Center uses this error message when the API credentials are invalid or when the IP address is not within the allowed range.
10000006	400	Invalid pageSize.
10000007	400	Invalid pageNumber.
10000012	400	Invalid date format.
10000013	404	Invalid ratePlan.
10000024	400	Invalid apiVersion.
10000030	400	Your role does not have access to this API function.
10000062	400	Access Denied.
10000441	400	Invalid RatePlan Version.
10000442	400	More than one RatePlan having the same name. Description: The rate plan name is not unique. Try using the rate plan version number along with the name to indicate a unique rate plan.
10000443	400	Invalid BillingCycleStart. Description: The billing cycle start date doesn't correspond to a valid billing cycle.
20000058	400	Requested resource not available for Shared Rate plan. Description: You cannot use shared rate plans in this function.
30000001	500	Unknown server error.
30000003	400	Invalid Usage Type.