Push notifications

This page describes how to use push notifications with the Reseller API.

Overview

The Reseller API uses the Pub/Sub API to deliver push notifications about Google Workspace subscription events. For example, you can set up push notifications to be notified when customer 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 recommended, but you can use more specific Pub/Sub permissions.

Create a topic

To create a topic, register with the Reseller API using the resellernotify.register method. This method takes a service account email address as a parameter. Only service accounts authorized by this method can subscribe to your 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.

Example response:

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

To authorize more service accounts, call resellernotify.register again.

Revoke access for a service account

The Reseller API can 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

After creating the Pub/Sub topic, set up how your application consumes change events. Choose one of the following:

  • 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 queued changes.

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 you previously created.
  • PUSH_NOTIFICATION_ENDPOINT: Your push notification handler endpoint.

A successful response returns an HTTP 200 status code. 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 a base64-encoded JSON string.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

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 dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Event types

Possible event types:

  • 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 an annual 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 subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: Suspension was revoked.
  • SUBSCRIPTION_CANCELLED: Subscription was canceled. See subscription_cancellation_reason. Can also detect transfers.
  • SUBSCRIPTION_CONVERTED: Subscription was converted. Example cases:
    • Convert direct subscription to reseller subscription.
    • Convert paid subscription to grace offer.
    • Convert online subscription to offline subscription.
  • SUBSCRIPTION_UPGRADE: Subscription SKU was upgraded. Example: Google Workspace Business Starter to Business Standard.
  • SUBSCRIPTION_DOWNGRADE: Subscription SKU was downgraded. Example: Google Workspace Business Standard to Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED: License was assigned or revoked. Use to track seat count changes for Flexible subscriptions.

Subscription cancellation reasons

The cancellation reason is populated when event_type is SUBSCRIPTION_CANCELLED. Possible reasons:

  • TRANSFERRED_OUT: The customer transferred to direct billing or another reseller.
  • PURCHASE_OF_SUBSUMING_SKU: The customer upgraded to a SKU that overrides another. Example: A customer with Google Workspace Business Starter and Vault upgrades to Business Plus, which includes Vault.
  • RESELLER_INITIATED: The reseller canceled the subscription.
  • OTHER: The subscription was canceled for another reason.

Subscription suspension reasons

The suspension reason is populated when event_type is SUBSCRIPTION_SUSPENDED. Possible reasons:

  • PENDING_TOS_ACCEPTANCE: The customer hasn't accepted the Google Workspace Resold Terms of Service.
  • RENEWAL_WITH_TYPE_CANCEL: The customer's commitment ended and service was canceled.
  • RESELLER_INITIATED: The reseller manually suspended the subscription.
  • TRIAL_ENDED: The customer's trial expired without a non-trial plan selection.
  • OTHER: The customer is suspended for an internal Google reason, such as abuse.

Pub/Sub limitations

Push notification ordering isn't always sequential. Messages might be delivered multiple times or not at all. We recommend using reseller.subscriptions.get on changed subscriptions to pull the current state.