Pub/Sub Notifications

  • Partners can receive real-time notifications about subscription and purchase order state changes via Cloud Pubsub.

  • These notifications provide crucial information for detecting and processing events like cancellations and refunds.

  • Each partner is assigned unique Cloud Pubsub Topic IDs and needs to allow-list their service accounts for access.

  • Notification messages include data and attributes fields containing details about the specific event and resource.

  • Partners can use filters to receive only the notifications relevant to their needs.

Partners can receive notifications of the state changes on subscriptions and purchase orders during their life cycles and should be treated as the source of truth. Partners need to subscribe to the corresponding Cloud Pubsub topic provisioned by Payments Reseller Subscription backend.

Google Cloud Pub/Sub Notifications are used to detect and process certain events, such as:

  • Informing you about recent sign-ups.
  • Notifying you when user subscriptions have been auto-renewed by the system.
  • Alerting you about users who have deleted their Google Accounts.
  • Warning you about users whose subscriptions have been terminated by Google.

This typically requires receiving over 10 million Pub/Sub calls monthly. More information on billing can be found here.

Subscription Lifecycle

state transitions

Subscribing to Cloud Pubsub

You must provide your Google team with accounts you wish to be allow-listed to Subscribe to the Topics.

To set up Pub/Sub, you must first receive your Pub/Sub Topics from Google.

  1. Verify Pub/Sub Topics: Ensure the provided Pub/Sub Topics are correct. These will be provided to you by your Google integration team.
  2. You should determine what type of subscription you want to use. You should follow the relevant instructions for the Pub/Sub Subscription method you decide on.
  3. You should refer to Best practices to subscribe to a Pub/Sub Topic for more information.

How to process a notification

A notification is sent asynchronously after a subscription or purchase order is updated.

The notification reflects the latest state of the resource, not necessarily the snapshot at the time of the triggering action.

For example, if a subscription state changes multiple times within a short period of time, you might receive the identical notifications afterwards, all of them report the latest subscription state.

Due to the asynchronous nature, it is also possible for notifications of the same resource to arrive out of order. The sequenceNumber can be used to determine the freshness.

Notification Specification

The notification is encoded in the pubsub message using the following specification:

  • data: subscription resource, or purchase order resource in json format. It is base64-encoded in Pubsub RESTful API. Pubsub SDK may return decoded value directly, see java example.

  • attributes: A map containing additional information related to the subscription in the message. Can be accessed via attributes field in the PubsubMessage, see java example. Currently has the following keys that are returned in the Map

Subscription Pubsub message attributes:

Key Description
sequenceNumber The sequence number is a unique number within a subscription (not globally unique) that can be used to handle idempotency and out-of-order notifications. Please store this sequence number for each subscription and ignore any notifications if the received sequence number equal or smaller than the stored sequence number of the same subscription.
state Value corresponds to the String value of the enum

State
cancellationReason This entry will be populated only when CancellationReason is present in the message.
Value corresponds to String value of enum

CancellationReason
endUserEntitled If an end user has linked their Google Account to the subscription. Possible values are true and false.

Purchase order Pubsub message attributes:

Key Description
sequenceNumber The sequence number is a unique number within a purchase order (not globally unique) that can be used to handle idempotency and out-of-order notifications. Recipients of notifications may want to persist this number and process a request only if the current sequence number is greater than the previous sequence number for a purchase order.

Partners can use attributes to create topic subscription with a filter in order to receive only messages that matches the filter. For instance, use filter such as attributes.state = "STATE_CANCELLED" AND attributes.cancellationReason = "CANCELLATION_REASON_ACCOUNT_CLOSED" to receive messages for cancelled subscriptions due to account closure. See docs for more information.

Following fields are not used:

  • orderingKey

Subscription notification examples:

  • User activating the service:
{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQUNUSVZFIiwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "state": "STATE_ACTIVE"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}

// The `data` field encodes the following subscription resource:
{
  "name": "partners/demo/subscriptions/65a30df9-8665-42a8-8c7b-03dce9135e9a",
  "products": ["partners/demo/products/PTPD-12345678"],
  "partnerUserToken": "215493425166",
  "redirectUri": "https://www.example.com",
  "serviceLocation": {
    "regionCode": "US"
  },
  "cycleEndTime": "2021-02-02T15:01:23Z",
  "freeTrialEndTime": "2021-01-02T15:01:23Z",
  "endUserEntitled": true,
  "state": "STATE_ACTIVE",
  "provisionTime": "2020-10-02T15:01:20Z",
  "createTime": "2020-10-02T15:01:23Z",
  "updateTime": "2020-10-08T15:01:23Z",
  "renewalTime": "2021-02-02T15:01:23Z",
  "lineItems": [{
    "product": "partners/demo/products/PTPD-12345678",
    "state": "LINE_ITEM_STATE_ACTIVE",
    "description": "Base Plan",
    "recurrenceType": "LINE_ITEM_RECURRENCE_TYPE_PERIODIC",
    "amount": {
      "currencyCode": "USD",
      "amountMicros": "12990000"
    },
    "lineItemIndex": 0
  }]
}
  • Subscription cancellation. It can be initiated by the partner or Google.
{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQ0FOQ0VMTEVEIiwKICAiY2FuY2VsbGF0aW9uRGV0YWlscyI6IHsKICAgICJyZWFzb24iOiAiQUNDT1VOVF9DTE9TRUQiCiAgfSwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "state": "STATE_CANCELLED",
    "cancellationReason": "CANCELLATION_REASON_ACCOUNT_CLOSED"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}

// The `data` field encodes the following subscription resource with cancellation details:
{
  "name": "partners/demo/subscriptions/65a30df9-8665-42a8-8c7b-03dce9135e9a",
  "products": ["partners/demo/products/PTPD-12345678"],
  "partnerUserToken": "215493425166",
  "redirectUri": "https://www.example.com",
  "serviceLocation": {
    "regionCode": "US"
  },
  "cycleEndTime": "2021-02-02T15:01:23Z",
  "freeTrialEndTime": "2021-01-02T15:01:23Z",
  "renewalTime": "2021-02-02T15:01:23Z",
  "endUserEntitled": true,
  "state": "STATE_CANCELLED",
  "cancellationDetails": {
    "reason": "CANCELLATION_REASON_ACCOUNT_CLOSED"
  },
  "provisionTime": "2020-10-02T15:01:20Z",
  "createTime": "2020-10-02T15:01:23Z",
  "updateTime": "2020-10-08T15:01:23Z",
  "lineItems": [{
    "product": "partners/demo/products/PTPD-12345678",
    "state": "LINE_ITEM_STATE_ACTIVE",
    "description": "Base Plan",
    "recurrenceType": "LINE_ITEM_RECURRENCE_TYPE_PERIODIC",
    "amount": {
      "currencyCode": "USD",
      "amountMicros": "12990000"
    },
    "lineItemIndex": 0
  }]
}

Purchase Order notification examples:

  • Upon subscription renewal charge :
{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQUNUSVZFIiwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "sequenceNumber": "1680291396"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}


// The `data` field encodes the following purchase order resource with charged details:
{
  "name": "partners/demo_partner/purchaseorders/be587593-9b44-4e6d-90b2-08db29689362",
  "partnerUserToken": "09DDE00156E31A9A909E0004AC1EA1AD",
  "lineItems": [{
    "product": "partners/demo_partner/products/844b3390-fc0b-4cce-9881-2531aa9ac56d",
    "description": "Base Plan",
    "amount": {
      "currencyCode": "USD",
      "amountMicros": "62990000"
    },
    "servicePeriod": {
      "startTime": "2023-03-25T17:33:47.503Z",
      "endTime": "2023-04-25T17:33:47.503Z"
    },
    "chargedDetails": {
      "priceDetails": {
        "pretaxAmount": {
          "currencyCode": "USD",
          "amountMicros": "62990000"
        },
        "taxAmount": {
          "currencyCode": "USD",
          "amountMicros": "0"
        },
        "totalAmount": {
          "currencyCode": "USD",
          "amountMicros": "62990000"
        }
      }
    }
  }],
  "subscriptionDetails": {
    "subscription": "partners/demo_partner/subscriptions/be587593-9b44-4e6d-90b2-08db29689362",
    "purchaseOrderType": "PURCHASE_ORDER_TYPE_RENEWAL"
  }
}