Get a plan definition

This GET operation retrieves a specific plan definition by the planDefinitionId. 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/<planDefinitionId>

HEADER INFO

tenant: <tenantName>

authorisation: HTTP Basic Auth

accept: application/hal+JSON

permissions: SPCM_PLAN_DEFINITION_READ_PERMISSION

URL parameters

There is one mandatory parameter.

Parameter Type Description

planDefinitionId

integer

A unique identifier for a plan definition which was assigned by the server upon creating the plan definition.

JSON response

The following example shows the JSON response for a request for a plan with a planDefinitionId of 192 (shown as id 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.

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.

renewOnConsumption

boolean

{define-renewOnConsumption}

  • true = yes

  • false = no

Default = false


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

example
HTTP/1.1 500
{
    "message": "Internal server error - [Failed to get session information]",
    "status": "error"
}

503

request rejected due to overload