Search for a plan definition

This GET operation searches for a plan definition using query parameters name and current as in the status of the plan definition. If successful, you receive an HTTP response code of 200 and a JSON response which includes all of the information for the requested plan definition.

See HTTP response codes for other response codes.

GET /pcc/spcm/planDefinitions?name=<PlanName>&current=true

HEADER INFO

tenant: <tenantName>

authorisation: HTTP Basic Auth

accept: application/hal+JSON

permissions: SPCM_PLAN_DEFINITION_READ_PERMISSION

URL query parameters

There are two possible query parameters.

If you use both query parameters, only plan definitions matching both criteria will be returned.
Parameter Type Description

name

string (max 255)

The name of the plan definition.

current

boolean

Indicates if a plan definition is current or not where true means the plan definition is current and false means it is not.

JSON response

The following example shows the JSON response for a request for a plan with a name of planDefinition01 (shown as name in the payload). This particular sample returns only some of the data types possible. You may see more when requesting other plan definitions.

See Plan definition descriptions for all possible data types. 
{
    "id": 192,
    "name": "planDefinition01",
        "validityPeriod": {
            "validityPeriod": "1week"
    },
    "grantedAmount" : {
        "volumeAmount" : 1000
    },
    "unitMeteringType": "VOLUME",
    "core": false,
    "recurring": false,
    "cost" : 100,
    "unitAmount": "1000",
    "planPrecedence": 0
}

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