Reminder: By Aug 31, 2024, all new apps and updates to existing apps must use Billing Library version 6 or newer. If you need more time to update your app, you will be able to request an extension until Nov 1, 2024. Learn more.

Real-time developer notifications reference guide

This topic lists and describes the types of Real-time developer notifications that you can receive from Google Play.

Encoding

Each publish made to a Cloud Pub/Sub topic contains a single base64-encoded data field.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

After you decode the base64-encoded data field, the DeveloperNotification contains the following fields:

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "testNotification": TestNotification
}

These fields are described in the following table.

Property name	Value	Description
version	string	The version of this notification. Initially, this is "1.0". This version is distinct from other version fields.
packageName	string	The package name of the application that this notification relates to (for example, `com.some.thing`).
eventTimeMillis	long	The timestamp when the event occurred, in milliseconds since the Epoch.
subscriptionNotification	SubscriptionNotification	If this field is present, then this notification is related to a subscription, and this field contains additional information related to the subscription. Note that this field is mutually exclusive with oneTimeProductNotification, voidedPurchaseNotification, and testNotification.
oneTimeProductNotification	OneTimeProductNotification	If this field is present, then this notification is related to a one-time purchase, and this field contains additional information related to the purchase. Note that this field is mutually exclusive with subscriptionNotification, voidedPurchaseNotification, and testNotification.
voidedPurchaseNotification	VoidedPurchaseNotification	If this field is present, then this notification is related to a voided purchase, and this field contains additional information related to the voided purchase. Note that this field is mutually exclusive with oneTimeProductNotification, subscriptionNotification, and testNotification.
testNotification	TestNotification	If this field is present, then this notification is related to a test publish. These are sent only through the Google Play Developer Console. Note that this field is mutually exclusive with oneTimeProductNotification, subscriptionNotification, and voidedPurchaseNotification.

SubscriptionNotification

A SubscriptionNotification contains the following fields:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "subscriptionId": string
}

Property name	Value	Description
version	string	The version of this notification. Initially, this is "1.0". This version is distinct from other version fields.
notificationType	int	The notificationType for a subscription can have the following values: (1) SUBSCRIPTION_RECOVERED - A subscription was recovered from account hold. (2) SUBSCRIPTION_RENEWED - An active subscription was renewed. (3) SUBSCRIPTION_CANCELED - A subscription was either voluntarily or involuntarily cancelled. For voluntary cancellation, sent when the user cancels. (4) SUBSCRIPTION_PURCHASED - A new subscription was purchased. (5) SUBSCRIPTION_ON_HOLD - A subscription has entered account hold (if enabled). (6) SUBSCRIPTION_IN_GRACE_PERIOD - A subscription has entered grace period (if enabled). (7) SUBSCRIPTION_RESTARTED - User has restored their subscription from Play > Account > Subscriptions. The subscription was canceled but had not expired yet when the user restores. For more information, see Restorations. (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED - A subscription price change has successfully been confirmed by the user. (9) SUBSCRIPTION_DEFERRED - A subscription's recurrence time has been extended. (10) SUBSCRIPTION_PAUSED - A subscription has been paused. (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED - A subscription pause schedule has been changed. (12) SUBSCRIPTION_REVOKED - A subscription has been revoked from the user before the expiration time. (13) SUBSCRIPTION_EXPIRED - A subscription has expired. (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED - A pending transaction of a subscription has been canceled.
purchaseToken	string	The token provided to the user's device when the subscription was purchased.
subscriptionId	string	The purchased subscription's product ID (for example, "monthly001").

Example

Here's an example of a notification for a new subscription purchase:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN",
    "subscriptionId":"monthly001"
  }
}

OneTimeProductNotification

A OneTimeProductNotification contains the following fields:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "sku": string
}

Property Name	Value	Description
version	string	The version of this notification. Initially, this will be "1.0". This version is distinct from other version fields.
notificationType	int	The type of notification. It can have the following values: (1) ONE_TIME_PRODUCT_PURCHASED - A one-time product was successfully purchased by a user. (2) ONE_TIME_PRODUCT_CANCELED - A pending one-time product purchase has been canceled by the user.
purchaseToken	string	The token provided to the user’s device when purchase was made.
sku	string	The purchased one-time product ID (for example, "sword_001")

Example

Here's an example of a notification for a new one-time purchase:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "oneTimeProductNotification":
  {
    "version":"1.0",
    "notificationType":1,
    "purchaseToken":"PURCHASE_TOKEN",
    "sku":"my.sku"
  }
}

VoidedPurchaseNotification

A VoidedPurchaseNotification contains the following fields:

Property Name	Value	Description
`purchaseToken`	`string`	The token associated with the purchase that has been voided. This information is provided to the developer when a new purchase occurs.
`orderId`	`string`	The unique order ID associated with the transaction that has been voided. For one time purchases, this represents the only order ID generated for the purchase. For auto-renewing subscriptions, a new order ID is generated for each renewal transaction.
`productType`	`int`	The `productType` for a voided purchase can have the following values: (1) `PRODUCT_TYPE_SUBSCRIPTION` - A subscription purchase has been voided. (2) `PRODUCT_TYPE_ONE_TIME` - A one-time purchase has been voided.
`refundType`	`int`	The `refundType` for a voided purchase can have the following values: (1) `REFUND_TYPE_FULL_REFUND` - The purchase has been fully voided. (2) `REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND` - The purchase has been partially voided by a quantity-based partial refund, applicable only to multi-quantity purchases. A purchase can be partially voided multiple times. Note when the remaining total quantity of a multi-quantity purchase is refunded, the `refundType` will be `REFUND_TYPE_FULL_REFUND`.

Example

Here's an example of a notification for a new voided purchase:

{
  "version":"1.0",
  "packageName":"com.some.app",
  "eventTimeMillis":"1503349566168",
  "voidedPurchaseNotification":
  {
    "purchaseToken":"PURCHASE_TOKEN",
    "orderId":"GS.0000-0000-0000",
    "productType":1
    "refundType":1
  }
}

Consuming VoidedPurchaseNotification

When your RTDN client receives a VoidedPurchaseNotification, note the following information:

packageName: This identifies the app.
eventTimeMillis: This informs the developer of the time the change in status occurred.
purchaseToken: The token provided to the user's device when the product was purchased.
orderId: This identifies the order associated with the voided transaction.
productType: This tells you if the voided purchase was an in-app purchase or a subscription.
refundType: This tells you the type of refund that voided the purchase.

If all you need to do for entitlement adjustments is locate the right purchase and order, then you have all the information you need at this point. To learn how to get additional information about the voided purchase, check out the Google Play Voided Purchases API, which is a pull model that provides additional data for voided purchases between a given timestamp.

For partially voided multi-quantity purchases, the refundableQuantity field provided by purchases.products contains the remaining number of purchased products that have not been voided.

TestNotification

A TestNotification contains the following fields:

{
  "version": string
}

Property name	Value	Description
version	string	The version of this notification. Initially, this is "1.0". This version is distinct from other version fields.

Example

Here's an example of a test notification:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}