Get usage for a plan

This GET operation requests the subscriber usage for a specific plan. If successful, you receive an HTTP response code of 200 as well as a JSON response body listing plan usage rules, counters, and general subscriber usage.

See HTTP response codes for other response codes.

GET /pcc/spcm/subscribers/<msisdn>/plans/<planId>/usage

HEADER INFO

tenant: <tenantName>

authorisation: HTTP Basic Auth

accept: application/vnd.com.tango.pcc.v2+json

permissions: SPCM_PLAN_READ_PERMISSION

URL parameters

There are two mandatory parameters.

Parameter Type Description

msisdn

string

The subscriber’s MSISDN in international format.

planId

string

The unique ID for the plan.


JSON response

The following example response shows the expected response from passing a recognised msisdn and planId in the URL.

To see all possible fields for the plan definitions, see plan definition type descriptions. 
{
    {
        "plan": {
        "planDefinition":
            "planDefinition": {
            "name": "TEST_1MB_1DAY_FUP",
            "identifier": "101",
            "unitAmount": "1048576",
            "unitMeteringType": "volume",
            "cost": 100,
            "validityPeriod": "1day",
            "classification": "DATA",
            "precedence": 2,
            "recurring": false,
            "core": false,
            "summary": "Add-on plan, single-use, 1MB volume, 1 day validity, QoS Downgrade
            at 75%",
            "maxDeactivationCount": 3,
            "recycleRollOverLimit": 0,
            "accumulationPermitted": false,
            "dpsEnabled": false,
            "shared": false,
            "activationModeType": "default",
            "activationPendingTimeoutPeriod": "",
            "validityCarryForward": false,
            "validityCarryForwardRankEnabled": false,
            "validityCarryForwardRank": 0,
            "validityCarryForwardAccumulation": false,
            "deferredActivationAllowed": false,
            "loanPurchaseAllowed": false,
            "recommendationOnPurchase": false,
            "version": 1,
            "description": "Test plan - 1 day single-use add-on with FUP",
            "allowed": false,
            "grantedAmount": 555
        },
        "id": "70314",
        "state": "active",
        "purchaseTimestamp": "2018-06-12T12:13:44.000+01:00",
        "activationTimestamp": "2018-06-12T12:13:44.000+01:00",
        "expiryTimestamp": "2018-06-13T00:01:00.000+01:00",
        "updateTimestamp": "2018-06-12T12:14:02.000+01:00",
        "cancelled": false,
        "usage": 790528,
        "deactivationCount": 0,
        "allowedUnitAmount": "1048576",
        "occurrenceCount": 1,
        "usageState": "available",
        "boosterVolumeCount": 0,
        "boosterValidityCount": 0,
        "loanAmount": 0
        },
    "ruleListType": {
        "length": 2,
        "rule": [
        {
            "name": "fupRule",
            "id": "72892",
            "type": "usage",
            "state": "violated",
            "value": "786432",
            "usage": {
                "amount": 790528,
                "unitMeteringType": "volume"
             },
            "pccProfile": [
                {
                "alias": "fup",
                "qosProfileName": "QOS_min256_max256",
                "serviceProfileName": "Default_SERVICES",
                "chargingProfileName": "Prepaid Postpaid Bundle"
                }
        ],
            "ruleDefinition": {
                "name": "fupRule",
                "id": "160",
                "summary": "QoS downgrade at 75% of volume limit",
                "updateType": "none",
                "maxDeactivationPeriod": "",
                "threshold": 786432
            },
            "action": [
                {
                "messageMethod": "sms",
                "name": "Fup_Notification"
                }
            ],
            "updateTimestamp": "2018-06-12T12:13:55.000+01:00"
        },
        {
            "name": "Plan Consumption Rule",
            "id": "72893",
            "type": "usage",
            "state": "active",
            "value": "1048576",
            "usage": {
                "amount": 790528,
                "unitMeteringType": "volume"
            },
            "pccProfile": [],
            "ruleDefinition": {
                "name": "Plan Consumption Rule",
                "id": "161",
                "updateType": "none",
                "threshold": 1048576
            },
            "action": [
            {
                "messageMethod": "none",
                "name": "Plan Consumed System Action"
            }
        ],
        "updateTimestamp": "2018-06-12T12:13:44.000+01:00"
                }
            ]
        }
    }


Plan type descriptions

Field Type Description

planDefinition

integer

The plan definition information for the plan.

See plan definition type information more details on what to expect within the plan definition information you receive.

maxOccurenceCount

integer

Specifies the maximum number of times this plan can recur.

options

  • 0 = no limit

  • 1 = does not auto-renew

Any value from 2 and higher specifies the number of times the plan will recur.

id

string

The unique identifier for the plan.

state

enum

The current state of the plan in its lifecycle.

options

  • available = unit metering type is available for the plan

  • consumed = unit meter type is consumed for this plan

purchaseTimestamp

dateTime

The time at which the plan was purchased.

Format is ISO 8601.

activationTimestamp

dateTime

The time at which the plan was activated.

Format is ISO 8601.

expiryTimestamp

dateTime

The time at which the plan will expire.

Format is ISO 8601.

updateTimestamp

dateTime

The time at which the plan was updated.

Format is ISO 8601.

cancelled

boolean

Flag that indicates if the plan has been cancelled.

options

  • true = cancelled

  • false = not cancelled

usage

long

The plan’s current usage. The unit type is defined in unitMeteringType in the plan definition.

deactivationCount

short

The number of times the plan has been deactivated.

purchaseSource

string

Identifies the source of the plan purchase such as PMI.

allowedUnitAmount

string

The current allowed plan amount (taken into account rollover, accumulation, and pro-rated data/validity).

occurrenceCount

integer

The number of times the plan recurred.

usageState

enum

The current usage state of the plan.

options

  • available = unit metering type is available for the plan

  • consumed = unit meter type is consumed for this plan

parkedTimestamp

dateTime

The time when the plan was parked for the first time during the current renewal.

Format is ISO 8601.

parkedNextRetryTimestamp

dateTime

The time when the next retry will be made.

Format is ISO 8601.

boosterVolumeCount

short

The number of times the plan used the volume booster.

boosterValidityCount

short

The number of times the plan used the validity booster.

Plan definition type descriptions

Field Type Description

id

integer

The unique identifier for the plan. This is assigned by the server upon creating a plan definition.

mandatory when updating a plan definition.

name

string (255)

The name of the plan definition.

mandatory when creating a plan definition.

unitAmount

string (255)

This tells you the number of units a plan definition provides. The unit type is defined in unitMeteringType.

mandatory when creating a plan definition.

unitMeteringType

enum

Defines the unit type. This can be time (seconds), volume (bytes), or credits (currency’s lowest denomination; for example a cent so 100 units equals $1).

mandatory when creating a plan definition.

cost

integer

The cost or purchasing the plan. Like unitMeteringType, the cost is in the lowest denomination of the currency (i.e., 1 cent so 100 units equals $1).

mandatory when creating a plan definition.

validityPeriod.validityPeriod

string (255)

A formatted string that displays for how long a plan definition exists. An example is 2days3hours2minutes.

mandatory when creating a plan definition.

validityPeriod.absoluteExpiryTime

string

Denotes the hour, minute, and second at which the plan will expire or renew.

NOTE: If not set, the plan will expire or renew relative to the purchase timestamp (timestamp + validity period). This format is hh:mm:ss.

precedence

integer

The precedence of the plan over other plans purchased by the subscriber where 0 is the highest precedence.

mandatory when creating a plan definition.

recurring

boolean

Denotes whether a plan is recurring or not where true is recurring and false is not.

mandatory when creating a plan definition.

core

boolean

Indicates if this plan is the core plan for the subscriber where true is the core plan and false is not.

mandatory when creating a plan definition.

summary

string (2048 char)

A brief summary describing the plan.

maxDeactivationCount

integer

The amount of times a plan definition can be deactivated.

maxOccurenceCount

integer

The maximum number of times a recurring plan can recur.

recycleRollOverLimit

integer

The maximum amount of unused data usage that can be carried forward when a plan is renewed.

mandatory when creating a plan definition.

accumulationPermitted

boolean

Indicates if accumulation is permitted where true is permitted and false is not.

mandatory when creating a plan definition.

dpsEnabled

boolean

Indicates whether DPS is enabled where true means DPS is enabled and false means it is not.

mandatory when creating a plan definition.

activateOnPurchase

boolean

Indicates if a plan is activated upon purchase where true means the plan is activated on purchase and false means it is not.

mandatory when creating a plan definition.

shared

boolean

Indicates if a plan is shared where true means it is shared and false means it is not shared.

mandatory when creating a plan definition.

version

integer

Denotes the version of the plan

mandatory when creating a plan definition.

shareQuotaMaxRecipients

integer

Specifies the maximum number of recipients with whom quota can be shared.

This is an optional field.

grantedAmount

integer

The chunk size that is granted to a data session. The session reports usage after using the granted amount.

The grantedAmount can be credit, volume, or time. This is determined by what is set in the unitMeteringType.

HTTP response codes

Code Description

200

success!

207

Multistatus response

Check out HTTP statuses for more details.
This is not applicable to all operations.

400

malformed request

401

unauthorised; bad username or password

403

forbidden; user does not have appropriate privileges

404

plan not found

409

conflict with target resource

This often occurs if the item already exists, such as a plan, group, or name.
This is not applicable to all operations.

412

failed validation; this typically means that a property was not set or a value is out of range.

example
HTTP 412
{
  "errors" : [
        {
          "field" : "name",
          "description" : "name is mandatory"
        }
    ]
}

422

failed processing (after passing validation).

example
HTTP 422
{
    "message": "Subscriber max plan count exceeded",
    "errorCode": 1
}

500

internal error

503

request rejected due to overload