Push Notifications

Overview

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

Prerequisites

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

Enable the Cloud Pub/Sub API in your developer console project.
Familiarize yourself with the pub/sub concepts and data models.
Verify ownership of your domain. This is required to consume the notification feed via webhooks. You can find the domain verification page in the Google API Console.

Create a topic

To create a topic, you need to register with the G Suite 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://www.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 G Suite Reseller API also provides the ability to unregister service accounts using the resellernotify.unregister endpoint.

POST https://www.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:

Topic: A Pub/Sub notification feed. You create this by calling resellernotify.register.
Project: The developer console project of the service account subscribed to the topic.
Subscription: 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. You must verify this endpoint in your Developer Console project.

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",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "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 switched from G Suite Basic to G Suite Business.
SUBSCRIPTION_DOWNGRADE: Subscription SKU was switched from G Suite Business to G Suite Basic.
SEATS_CHANGED: Number of seats in use for a Flex account has changed.
LICENSE_ASSIGNMENT_CHANGED: License was assigned to or revoked from a user.

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 G Suite and Drive upgrades to G Suite Business, the Drive subscription is subsumed because it is included with G Suite Business.
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 G Suite 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.