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 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 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.