# Push Notifications

## Overview

The Google Mobile Data Plan Sharing API also allows an operator to send
notifications to a user by pushing a
[PlanStatus](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.planStatuses#PlanStatus).

The API currently supports 7 types of notifications.

1. **Low Balance** : when [PlanModule](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).coarseBalanceLevel is set to [LOW_QUOTA](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#balancelevel)
2. **Out of Data** : when [PlanModule](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).coarseBalanceLevel is set to [OUT_OF_DATA](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#balancelevel). If in addition to this, the [PlanModule](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).overUsagePolicy is set to PAY_AS_YOU_GO, then the user will be notified that they are about to enter pay as you go mode.
3. **Data Expiration Warning** : when [PlanModule](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).planModuleState is set to [EXPIRING_SOON](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#planstate)
4. **Plan Activation** : when [PlanModule](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).planModuleState is set to [NEWLY_ACTIVE](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#planstate)
5. **Pay as you go** : when [AccountInfo](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.AccountInfo).payAsYouGoCharge is populated with the amount that the user has spent.
6. **Account top up** : when [AccountInfo](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.planStatuses#AccountInfo).accountTopUp and [AccountInfo](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.planStatuses#AccountInfo).accountBalance are populated. Both these fields are required to send the account top up notification to the user. If units and nanos in [AccountInfo](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.planStatuses#AccountInfo).accountTopUp are set to zero, then the top up amount is not in the notification.
7. **Data Expiration** : when [PlanModule](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#PlanStatus.PlanModule).planModuleState is set to [EXPIRED](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.clients.users.planStatus#planstate). This is for plans that are already expired.

One notification is sent to the user for each field set. If multiple
`coarseBalanceLevel` or `planModuleState` fields are set in a single
`PlanStatus`, then an equal number of notifications will be sent to the user.

## Requirements

A notification
[PlanStatus](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/v1/operators.planStatuses#PlanStatus) SHOULD
contain as much information as possible about the user's mobile plan. For each
type of notification, the Data Plan Sharing API also defines a minimum set of
fields which are required to build the notification text. The operator MUST
include these fields in a notification PlanStatus.

| Notification | Required Fields |
|---|---|
| Low Balance | PlanModule.moduleName, PlanModule.byteBalance.remainingBytes |
| Out of Data | PlanModule.moduleName |
| Data Expiration Warning | PlanModule.moduleName, PlanModule.expirationTime |
| Plan Activation | PlanModule.moduleName |
| Data Expiration | PlanModule.moduleName |