Push notifications

Overview

The Reseller API uses the Pub/Sub API to deliver push notifications about different Google Workspace subscription events. For example, you can set up push notifications in order to be notified when your customers' subscription statuses change.

Prerequisites

  • Enable the Pub/Sub API for your Google Cloud project.
  • Grant Pub/Sub IAM roles to your service account on your Cloud project. Granting the roles/pubsub.editor role is a good compromise (easy and not too broad), but you might want to use more specific Pub/Sub permissions.

Create a topic

To create a topic, you need to register with the Reseller API by using 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.

The following 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 Reseller API also provides the ability to unregister service accounts by 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

After you have create the Pub/Sub topic, you need to set up how your application consumes your change events. Choose one of the following options:

  • Push subscription: You supply an HTTP POST callback. 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.

The following is an example request to subscribe to a topic:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Replace the following:

  • PROJECT: Your Google Cloud project.
  • SUBSCRIPTION_NAME: An identifying name for your subscription.
  • TOPIC_NAME: The Pub/Sub topic that you previously created.
  • PUSH_NOTIFICATION_ENDPOINT: Your push notification handler endpoint.

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

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "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/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

The following 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

The following list contains all possible event type:

  • 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 event isn't 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 as follows:

    • 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. You can use this event 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 following are possible cancellation reasons:

  • 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 Google 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 suspension reason is populated when the event_type is SUBSCRIPTION_SUSPENDED. The following are possible suspension reasons:

  • PENDING_TOS_ACCEPTANCE: The customer hasn't 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 didn't 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 isn't guaranteed. Messages might 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.