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 thesubscription_suspension_reasons
field.SUBSCRIPTION_SUSPENSION_REVOKED
: Suspension was revoked for a previously suspended subscription.SUBSCRIPTION_CANCELLED
: Subscription was cancelled. See thesubscription_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.