REST Resource: operators.clients.users.planStatus

Resource: PlanStatus

PlanStatus contains details of all top-level mobile service package a user has purchased.

JSON representation 
{
  "name": string,
  "plans": [
    {
      object (Plan)
    }
  ],
  "languageCode": string,
  "expireTime": string,
  "updateTime": string,
  "title": string,
  "subscriberId": string,
  "accountInfo": {
    object (AccountInfo)
  },
  "uiCompatibility": enum (UiCompatibility),
  "notifications": [
    enum (NotificationType)
  ],
  "planInfoPerClient": {
    object (PlanInfoPerClient)
  },
  "cpidState": enum (CpidState)
}
Fields
name

string

The resource name of the PlanStatus in the following format: operators/{asn_id}/planStatuses/{userKey}. The name is ignored when creating a PlanStatus entry.
plans[]

object (Plan)

List of plans owned by this user.
languageCode

string

Required. The BCP-47 language code, such as "en-US" or "sr-Latn". For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
expireTime

string (Timestamp format)

Required. Time when the shared plan group information becomes outdated. PlanStatus will not be served to applications after this time. Expire time must be in the future.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Required. Time when the data plan agent (DPA) fetched the plan status information from backend systems. Could be used to determine how recent the plan status information is. Update time must be in the past but cannot be more than 30 days old.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
title

string

Title of the contract that user has with the operator. This will be shown in the UI header.
subscriberId

string

Unique stable identifier in carrier system to identify the user.
accountInfo

object (AccountInfo)

Required for prepaid users. Information about the user account balance.
uiCompatibility

enum (UiCompatibility)

Determines if the PlanStatus can be shown to the user in a user interface. When set to UI_INCOMPATIBLE, the PlanStatus can be used for sending notifications to the user but will not be used for showing the plan information to user.
notifications[]

enum (NotificationType)

Contains the list of types of notifications sent to the user by GTAF. GTAF ignores this field if it is populated by the caller.
planInfoPerClient

object (PlanInfoPerClient)

Data plan information relevant to a particular Google client.
cpidState

enum (CpidState)

Status of the CPID for associated with this plan status.

Plan

Details of user's mobile plan, which is the top-level mobile service package that a subscriber purchases. The plan can be as simple as "10 GB mobile data for 30 days" or it can be defined as a collection of components (which we refer to as plan modules). For example, ACME plan 199, described as "2GB data, unlimited whatsapp + unlimited wechat, and 1GB spotify", contains three plan modules.

JSON representation 
{
  "planName": string,
  "planId": string,
  "planCategory": enum (PlanCategory),
  "expirationTime": string,
  "planModules": [
    {
      object (PlanModule)
    }
  ],
  "planState": enum (PlanState)
}
Fields
planName

string

Name of the user's mobile plan.
planId

string

Required. Plan identifier, used to refer to the plan during offers, etc.
planCategory

enum (PlanCategory)

Prepaid or postpaid plan.
expirationTime

string (Timestamp format)

Required. When this plan expires. For most plans, this should be equal to the maximum of all plan module specific expiration times. For plans that periodically refresh module quota, this should be the overall plan expiration time, the time at which plan modules stop refreshing. This field should be omitted if the plan does not expire.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
planModules[]

object (PlanModule)

Detailed plan modules (sub-plans) information.
planState

enum (PlanState)

State of user plan e.g. active, inactive etc.

PlanCategory

Possible plan category types.

Enums
PLAN_CATEGORY_UNSPECIFIED Unspecified.
PREPAID Prepaid plan.
POSTPAID Postpaid plan.

PlanModule

Info of each data plan module (or sub-plan) inside a plan.

JSON representation 
{
  "coarseBalanceLevel": enum (BalanceLevel),
  "trafficCategories": [
    enum (PlanModuleTrafficCategory)
  ],
  "expirationTime": string,
  "overUsagePolicy": enum (OverUsagePolicy),
  "maxRateKbps": string,
  "description": string,
  "moduleName": string,
  "usedBytes": string,
  "planModuleState": enum (PlanState),
  "refreshPeriod": enum (RefreshPeriod),

  // Union field balance can be only one of the following:
  "byteBalance": {
    object (ByteQuota)
  },
  "timeBalance": {
    object (TimeQuota)
  }
  // End of list of possible types for union field balance.
}
Fields
coarseBalanceLevel

enum (BalanceLevel)

Coarse balance information.
trafficCategories[]

enum (PlanModuleTrafficCategory)

List of traffic categories that will be charged against this plan module.
expirationTime

string (Timestamp format)

Required. Plan module specific expiration time. For plan modules with quota that refreshes periodically, this is the time of the next module refresh. This field should be omitted if the plan module does not expire.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
overUsagePolicy

enum (OverUsagePolicy)

Over usage policy, e.g., throttled.
maxRateKbps

string (int64 format)

Max data rate permitted by this plan module in Kbps. The actual data rate observed is between 0 and maxRateKbps depending on network conditions. Omitting maxRateKbps or setting it to 0 indicates that no throttling is to be performed for this plan module.
description

string

Required. Plan module description, may get surfaced to user and should be close to the market description of this plan module.
moduleName

string

Required. Name of the plan module.
usedBytes

string (int64 format)

Total number of bytes used by the user from this plan module.
planModuleState

enum (PlanState)

State of the plan module e.g. active, inactive etc.
refreshPeriod

enum (RefreshPeriod)

The refresh period of this plan module, or REFRESH_PERIOD_NONE if the plan module does not refresh its quota. Plan modules that refresh quota will do so once every refresh period.
Union field balance. Required. Plan module balance information, should be one of the following: byte_balance, time_balance, coarse_balance_level. balance can be only one of the following:
byteBalance

object (ByteQuota)

Bytes based plan module balance info. For modules that refresh periodically, this field represents the byte balance per refresh period.
timeBalance

object (TimeQuota)

Time based plan module balance info. For modules that refresh periodically, this field represents the time balance per refresh period.

ByteQuota

Bytes based plan module quota/balance information.

JSON representation 
{
  "quotaBytes": string,
  "remainingBytes": string
}
Fields
quotaBytes

string (int64 format)

Module quota in bytes. For unlimited plans, this should be set to 2^63 - 1 (9223372036854775807).
remainingBytes

string (int64 format)

Required for low balance notifications. Remaining quota balance in bytes.

TimeQuota

Time based plan module quota/balance information.

JSON representation 
{
  "quotaMinutes": string,
  "remainingMinutes": string
}
Fields
quotaMinutes

string (int64 format)

Module quota in minutes for time-based plan, e.g., 180 minutes.
remainingMinutes

string (int64 format)

Remaining quota balance in minutes for time-based plan, e.g., 40 minutes.

BalanceLevel

Coarse plan module data balance info.

Enums
BALANCE_LEVEL_UNSPECIFIED Unspecified.
NO_PLAN No data plan.
OUT_OF_DATA Data balance is zero.
LOW_QUOTA Data balance (or time left) is equal to or less than 10-25% of the original pack balance (or time). Carriers MAY determine the exact threshold for each pack as they deem appropriate.
HIGH_QUOTA Data balance (or time left) is more than 10-25% of the original pack balance (or time). Carriers MAY determine the exact threshold for each pack as they deem appropriate. Data balance is high.

PlanModuleTrafficCategory

Plan module traffic category, which describes the set of application traffic that falls into a particular plan module.

Enums
PLAN_MODULE_TRAFFIC_CATEGORY_UNSPECIFIED Unspecified.
GENERIC Generic, applies to all traffic.
VIDEO All video traffic.
VIDEO_BROWSING Video discovery (browsing) traffic, which refers to all video app traffic excluding the video/audio streaming part.
VIDEO_OFFLINE Video offline traffic, which is the sum of VIDEO_BROWSING and video/audio offline (non-streaming) traffic.
MUSIC Music app traffic.
GAMING Gaming app traffic.
SOCIAL Social app traffic.
MESSAGING Messaging app traffic.
APP_STORE App store traffic, such as updating or downloading a new app.

OverUsagePolicy

Over usage policy: what happens when the user runs out of quota.

Enums
OVER_USAGE_POLICY_UNSPECIFIED Unspecified.
THROTTLED Speed is throttled.
BLOCKED Connection is blocked.
PAY_AS_YOU_GO Pay per use.

PlanState

Enum representing different state of user's plan/plan module.

Enums
ACTIVE Plan/PlanModule is active and the user can use data offered as part of the module.
INACTIVE Plan/Plan Module is inactive and while the user still has the module, user cannot use data that is part of the module. This could happen if the module only offers data during certain times of the day or if the user has purchased a module but it's not activated yet.
EXPIRING_SOON Plan/PlanModule is going to expire soon. Caller should choose appropriate level for determining when to set this value. This automatically means that plan is active.
NEWLY_ACTIVE Plan/PlanModule that was previously inactive or non-existent has just been activated. This state should only be used for a very short period after the activation time, otherwise the ACTIVE state should be used instead. Data plan status notifications sent with NEWLY_ACTIVE modules should be sent with a short TTL, since the NEWLY_ACTIVE status will become inaccurate very quickly.
EXPIRED Plan/PlanModule is expired. Setting this enum value triggers a plan expired notification.

RefreshPeriod

Represents a refresh period, the regular interval at which a plan module resets.

Enums
REFRESH_PERIOD_NONE No refresh period. Used when the plan module is not recurring.
DAILY The plan module resets every day.
MONTHLY The plan module resets every month.
BIWEEKLY The plan module resets every two weeks.
WEEKLY The plan module resets every week.

AccountInfo

Information about prepaid user's account balance.

JSON representation 
{
  "accountBalance": {
    object (Money)
  },
  "loanBalance": {
    object (Money)
  },
  "unpaidLoan": {
    object (Money)
  },
  "accountBalanceStatus": enum (AccountBalanceStatus),
  "validUntil": string,
  "payAsYouGoCharge": {
    object (Money)
  },
  "accountTopUp": {
    object (Money)
  }
}
Fields
accountBalance

object (Money)

Required. Account balance remaining on the user account.
loanBalance

object (Money)

Required if applicable. Account balance remaining on the user account that was added by a monetary loan from the carrier. If present, field accountBalance does not include this balance.
unpaidLoan

object (Money)

Amount of money user owes carrier due to monetary loans.
accountBalanceStatus

enum (AccountBalanceStatus)

Required. Indicates the status of the account balance. In case of a mismatch between validUntil time and accountBalanceStatus field, we use accountBalanceStatus.
validUntil

string (Timestamp format)

Required. The time until which the account balance is valid. This field will be used to show "Invalid in

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
payAsYouGoCharge

object (Money)

The amount of money the user has spent by using the plan in pay as you go state. If this field is populated by the carrier when sharing account information with GTAF, GTAF will attempt to send a notification to the user indicating that they are spending money in a pay as you go state.
accountTopUp

object (Money)

Required for account top up notification. The amount of money the user has added to their account balance. If this field is populated by the carrier when sharing account information with GTAF, GTAF will attempt to send a notification to the user indicating that their account has been topped up.

Money

Represents an amount of money with its currency type.

JSON representation 
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
Fields
currencyCode

string

The 3-letter currency code defined in ISO 4217.
units

string (int64 format)

The whole units of the amount. For example if currencyCode is "USD", then 1 unit is one US dollar.
nanos

integer

Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If units is positive, nanos must be positive or zero. If units is zero, nanos can be positive, zero, or negative. If units is negative, nanos must be negative or zero. For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

AccountBalanceStatus

Status of the user wallet.

Enums
VALID The user account balance is valid and can be used to make purchases.
INVALID User account balance is invalid and cannot be used without making changes to the account.

UiCompatibility

Enum representing if the PlanStatus being shared can be shown to the user.

Enums
UI_COMPATIBILITY_UNSPECIFIED By default we will assume that the PlanStatus is UI compatible.
UI_COMPATIBLE Indicates that the entire PlanStatus is UI compatible and the plan information can be shown to the user.
UI_INCOMPATIBLE Indicates that the PlanStatus is not UI compatibble. Fields can be used for sending notifications to the user but cannot be used for showing plan information to the user.

NotificationType

The type of notification being sent to the user of Mobile Data Plan settings.

Enums
NOTIFICATION_UNDEFINED Unknown notification genre type
NOTIFICATION_LOW_BALANCE_WARNING Notification that warns users for low balance
NOTIFICATION_DATA_EXPIRATION_WARNING Notification that warns users the data plan is going to expire
NOTIFICATION_OUT_OF_DATA Notification that users run out of data
NOTIFICATION_PLAN_ACTIVATION Notification that a user's purchased plan is now active
NOTIFICATION_PAY_AS_YOU_GO A notification informing the user that they are paying for data in a pay as you go state.
NOTIFICATION_ACCOUNT_TOP_UP A notification informing the user that they have topped up their account balance.
NOTIFICATION_DATA_EXPIRED A notification informing the user that their data plan has expired.

PlanInfoPerClient

Data plan information relevant to a particular Google client.

JSON representation 
{
  "youtube": {
    object (YouTube)
  },
  "androidSystemInfo": {
    object (AndroidSystemInfo)
  }
}
Fields
youtube

object (YouTube)

YouTube related plan information.
androidSystemInfo

object (AndroidSystemInfo)

Plan information relevant for Android System.

YouTube

Data plan information relevant to YouTube.

JSON representation 
{
  "rateLimitedStreaming": {
    object (RateLimitedStreaming)
  }
}
Fields
rateLimitedStreaming

object (RateLimitedStreaming)

YouTube Plan Aware Streaming (PAS) feature which limits bitrate of video being delivered.

RateLimitedStreaming

Data plan information to enable YouTube to enhance rate limited streaming user experience.

JSON representation 
{
  "maxMediaRateKbps": integer
}
Fields
maxMediaRateKbps

integer

The YouTube bit rate supported for this user in kbps (1000's of bits per second).

AndroidSystemInfo

Data plan information relevant to the entire Android system.

JSON representation 
{
  "cellularInfo": [
    {
      object (CellularInfo)
    }
  ]
}
Fields
cellularInfo[]

object (CellularInfo)

Per connection type cellular information. For example, there will be one cellularInfo message for each connection type like 4G, 5G etc.

CellularInfo

Information about a cellular connection that the plan offers the user.

JSON representation 
{
  "connectionType": enum (ConnectionType),
  "meteredness": enum (Meteredness)
}
Fields
connectionType

enum (ConnectionType)

The type of connection that the operator is providing to the user.
meteredness

enum (Meteredness)

The meteredness state of the user plan.

ConnectionType

Connection type: 2G, 3G, 4G

Enums
CONNECTION_TYPE_UNSPECIFIED Unspecified.
CONNECTION_2_G 2G.
CONNECTION_3_G 3G.
CONNECTION_4_G 4G.
CONNECTION_5_G 5G.
CONNECTION_ALL All types.

Meteredness

Type of plan that the user has

Enums
METEREDNESS_UNSPECIFIED GTAF does not know about the meteredness state of the user plan.
METEREDNESS_UNMETERED The user is on an unmetered plan.
METEREDNESS_METERED The user is on a metered plan.

CpidState

An enum for the carrier to represent the CPID state.

Enums
CPID_STATE_UNSPECIFIED The state of the CPID is unspecified. This is treated as if the CPID is valid.
CPID_INVALIDATED The CPID is invalidated and the client should fetch a new CPID from the CPID endpoint.

Methods

create

 Allows a mobile operator (identified by its unique Autonomous System Number (ASN)) to add new PlanStatus entry for a user to be used by a particular client.