Push Notifications

Stay organized with collections Save and categorize content based on your preferences.


The Google Workspace Reseller API uses the Cloud Pub/Sub API to deliver push notifications about different Google Workspace subscription events.


Before using the Pub/Sub API, make sure to follow these steps:

  • Enable the Cloud Pub/Sub API for your GCP project.
  • Grant Pub/Sub IAM roles to your service account on your GCP project. Granting roles/pubsub.editor is a good compromise (easy and not too broad), but you may want to use more specific Pub/Sub permissions.
  • Familiarize yourself with the Pub/Sub concepts and data models.

Create a topic

To create a topic, you need to register with the Google Workspace Reseller API via the resellernotify.register method. The resellernotify.register method takes a service account email address as a parameter. Only service accounts authorized by this method can subscribe to your newly created topic.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register

  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"

A successful response returns an HTTP 200 status code and a JSON response containing your Pub/Sub topic name. Below is an example response:

  "topicName": "projects/partner-watch/topics/C0abcdefg"

To authorize additional service accounts to use your topic, you can call resellernotify.register again.

Revoke access for a service account

The Google Workspace Reseller API also provides the ability to unregister service accounts using the resellernotify.unregister endpoint.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister

  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"

Subscribe to a topic

Once you have created the Pub/Sub topic, you need to set up how your application consumes your change events. You have two options to choose from:

  • Push subscription: You supply an HTTP POST callback. Cloud Pub/Sub uses this callback to notify your application about new events.
  • Pull subscription: Your application periodically makes an HTTP call to get all queued changes.

To subscribe to your topic, you need to call the Cloud Pub/Sub API. You may find the following terminology useful to know:

A Pub/Sub notification feed. You create this by calling resellernotify.register.
The developer console project of the service account subscribed to the topic.
A registration to receive notifications from a particular project on a particular topic. You may name subscriptions whatever you want, as the name is only for your own tracking purposes.

Below is an example request to subscribe to a topic:

PUT https://pubsub.googleapis.com/v1/projects/<your-project>/subscriptions/<subscription-name>

  "topic": "<topic-obtained-earlier>"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "https://mysite.com/pushHandler"

If you chose to use the push subscription method, you also need to provide your push notification handler endpoint.

A successful response returns an HTTP 200 status code. Below is an example response:

  "name": "projects/<your-project>/subscriptions/<subscription-name>",
  "topic": "<topic-obtained-earlier>",
  "pushConfig": {
    "pushEndpoint": "https://mysite.com/myhandler"
  "ackDeadlineSeconds": 10

Notification formats

The following is an example Pub/Sub notification. The message data is transmitted as a Base64 encoded JSON string.

  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  "subscription": "projects/<your-project>/subscriptions/<subscription-name>"

Below is the example message.data object after decoding:

  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"

Event Types

Possible event types are listed below:

  • NEW_SUBSCRIPTION_CREATED: A new subscription was created.
  • SUBSCRIPTION_TRIAL_ENDED: Trial ended for a subscription.
  • PRICE_PLAN_SWITCHED: Customer converted from a flexible plan to an annual plan. This is not triggered if the customer converts from a commitment-type plan to a flexible plan as part of a renewal.
  • COMMITMENT_CHANGED: Annual commitment was increased or decreased.
  • SUBSCRIPTION_RENEWED: An annual subscription was renewed.
  • SUBSCRIPTION_SUSPENDED: Subscription is suspended. See the subscription_suspension_reasons field.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Suspension was revoked for a previously suspended subscription.
  • SUBSCRIPTION_CANCELLED: Subscription was cancelled. See the subscription_cancellation_reason field. Can also be used to detect transfers.
  • SUBSCRIPTION_CONVERTED: Subscription was converted. Some example cases for this event are below:
    • Convert direct subscription to reseller subscription.
    • Convert paid subscription to grace offer.
    • Convert online subscription to offline subscription.
  • SUBSCRIPTION_UPGRADE: Subscription SKU was upgraded. For example, the subscription was upgraded from Google Workspace Business Starter to Business Standard.
  • SUBSCRIPTION_DOWNGRADE: Subscription SKU was downgraded. For example, the subscription was downgraded from Google Workspace Business Standard to Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED: License was assigned to or revoked from a user. This event can be used to reactively track seat count changes for Flexible subscriptions.

Subscription cancellation reasons

The subscription cancellation reason is populated when the event_type is SUBSCRIPTION_CANCELLED. The possible reasons are listed below:

  • TRANSFERRED_OUT: The customer has transferred to direct billing or to another reseller.
  • PURCHASE_OF_SUBSUMING_SKU: The customer has upgraded to a SKU that overrides another. For example, if a customer with Google Workspace Business Starter and Vault upgrades to Google Workspace Business Plus, the Vault subscription is subsumed because it is included with Google Workspace Business Plus.
  • RESELLER_INITIATED: The Reseller cancelled the subscription.
  • OTHER: The subscription was cancelled for some reason other than listed.

Subscription suspension reasons

The subscription cancellation reason is populated when the event_type is SUBSCRIPTION_SUSPENDED. The possible reasons are listed below:

  • PENDING_TOS_ACCEPTANCE: The customer has not logged in and accepted the Google Workspace Resold Terms of Services.
  • RENEWAL_WITH_TYPE_CANCEL: The customer's commitment ended and their service was cancelled at the end of their term.
  • RESELLER_INITIATED: The reseller manually suspended the subscription.
  • TRIAL_ENDED: The customer's trial expired, and the customer did not select a non-trial plan.
  • OTHER: The customer is suspended for an internal Google reason (for example, abuse).

Pub/Sub limitations

The Push notification ordering is not guaranteed. Messages may be delivered multiple times and in extreme situations, not at all. We recommend using reseller.subscriptions.get on all changed subscriptions to pull the current state.